DEV Community: Juan Torchia

PyTorch: the deep learning framework that won the war

Juan Torchia — Fri, 26 Jun 2026 12:02:16 +0000

This is part 5 of Awesome Curated: The Tools, where I do deep dives on the tools that pass the filter of our automatic curation system. If you landed here directly, I'd recommend starting from post #1 on Docker for Novices to understand how the process works. In the previous post we covered TensorFlow. Today it's its eternal rival — and, spoiler, the one that ended up winning the battle for researchers' hearts.

A couple years ago I was trying to reproduce an NLP paper. Completely normal thing in the academic world: the author publishes the code, you download it, you pray, and you try to get it to run. The paper was from 2019. The code was in TensorFlow 1.x. The absolute mess I got into with the versions, the static graphs, the tf.Session(), the placeholders... I lost half a day. Then I found an unofficial reimplementation in PyTorch. It worked in fifteen minutes. That difference — the feeling that the framework is working with you and not against you — is exactly what I'm going to try to explain in this post.

PyTorch doesn't need an introduction in 2025, but it deserves an honest explanation. Because there's a difference between knowing something exists and understanding why it won.

What it does

PyTorch is an open source machine learning library developed primarily by Meta AI (formerly Facebook AI Research). It's based on Torch, a scientific computing library that came from the Lua world, and since 2016 it's lived in Python as a first-class citizen.

The technical differentiator that defines it is its define-by-run approach (also called dynamic graph or eager execution). Unlike the original TensorFlow, which built a static computation graph and then executed it, PyTorch builds the graph as it executes. That might sound like an implementation detail, but in practice it changes everything: you can use a normal debugger, you can throw a print() in the middle of your neural network and actually see what's happening, you can have real conditional logic with Python ifs and fors.

import torch
import torch.nn as nn

# Simple neural network definition — pure Python, no magic
class SimpleNet(nn.Module):
    def __init__(self):
        super().__init__()
        # One hidden layer with 128 neurons, one output layer with 10 classes
        self.layers = nn.Sequential(
            nn.Linear(784, 128),  # input: flattened 28x28 image
            nn.ReLU(),            # activation function
            nn.Linear(128, 10)    # output: 10 classes (e.g. MNIST digits)
        )

    def forward(self, x):
        return self.layers(x)

# Instantiate the network and send it to GPU if available
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
net = SimpleNet().to(device)

# Autograd computes gradients automatically — free backprop
print(net)

Native GPU support via CUDA is transparent: you move a tensor with .to(device) and that's it. The autograd system automatically computes gradients for any operation you perform on tensors, which means implementing custom backpropagation is surprisingly manageable.

The ecosystem that grew around it is monumental: torchvision for computer vision, torchaudio for audio processing, HuggingFace Transformers (which runs primarily on PyTorch), PyTorch Lightning for structuring the training loop without losing your mind. If you're looking for the official implementation of some paper from the last five years, odds are high it's in PyTorch.

# Basic training loop — this is what Lightning later abstracts away
optimizer = torch.optim.Adam(net.parameters(), lr=1e-3)
criterion = nn.CrossEntropyLoss()

for epoch in range(10):
    for images, labels in dataloader:  # dataloader iterates the dataset
        images = images.to(device)
        labels = labels.to(device)

        optimizer.zero_grad()         # clear gradients from previous step
        predictions = net(images)     # forward pass
        loss = criterion(predictions, labels)  # compute error
        loss.backward()               # backward pass — autograd in action
        optimizer.step()              # update weights

    print(f"Epoch {epoch+1}, Loss: {loss.item():.4f}")

Why it's on the list

It showed up in 6 independent awesome lists. That's not a coincidence. The curation system we use in this series treats that consensus signal as a strong indicator: when different communities, with different criteria, all agree on recommending the same tool, something is going on.

What's going on with PyTorch is that it won the deep learning framework war — and it won it in the most convincing way possible: winning research first, then bleeding into production. Today the majority of papers at NeurIPS, ICML and similar conferences publish code in PyTorch. HuggingFace, which is basically the most important model hub in the world, is built on PyTorch. That creates a brutal flywheel: more researchers → more papers → more code → more adoption → more researchers.

Compared to TensorFlow (which we covered in the previous post), PyTorch has a more pythonic API and a significantly more human debugging experience. TensorFlow clawed back ground with Keras and eager execution, but the research community's perception was already set. For teams that build and experiment fast, PyTorch is the option with the least friction.

Meta's backing guarantees serious development resources. This isn't a hobby project at risk of being abandoned — it's critical infrastructure for one of the biggest players in the AI ecosystem.

When NOT to use it

First and foremost: if you're not doing deep learning, you probably don't need it. For classification, regression, decision trees, clustering — scikit-learn will get you the same result with a tenth of the complexity. PyTorch is a cannon, and not every problem is an elephant.

Second: production deployment has historically been its Achilles' heel. TensorFlow with TFLite or TensorFlow Serving has a longer, more battle-tested track record for serving models at the edge or in high-scale APIs. PyTorch improved this with TorchScript (for serializing models) and ONNX (for exporting to other runtimes), but those tools add real friction — and if you came from the m2cgen post, you already know that sometimes the most elegant solution to deployment is to not bring the framework to production at all.

Third: GPU memory consumption for large models is a world of its own. Without knowledge of the internals — gradient checkpointing, mixed precision, data parallelism — it's easy to run out of VRAM and have no idea why.

Wrapping up

PyTorch is one of those tools that has community consensus not because of marketing but because it solved a real problem better than the competition. The dynamic graph, the pythonic API, the ecosystem that grew around it — everything points in the same direction. If you're getting into deep learning, it's the most reasonable starting point that exists today.

This was entry #5 of Awesome Curated: The Tools. The series continues — every tool that shows up here went through a curation process that combines signal from multiple awesome lists, AI analysis, and my own human verdict. If you want to see the full journey from Docker to here, start from the first post. The next tool is already in the pipeline.

This article was originally published on juanchi.dev

PyTorch: el framework de deep learning que ganó la guerra

Juan Torchia — Fri, 26 Jun 2026 12:02:12 +0000

Esta es la parte 5 de Awesome Curated: The Tools, donde hago deep dives en las herramientas que pasan el filtro de nuestro sistema de curación automático. Si llegaste directo acá, te recomiendo arrancar desde el post #1 sobre Docker for Novices para entender cómo funciona el proceso. En el post anterior estuvimos con TensorFlow. Hoy toca su eterno rival — y, spoiler, el que terminó ganando la batalla por los corazones de los investigadores.

Hace un par de años estaba intentando reproducir un paper de NLP. Cosa de todos los días en el mundo académico: el autor publica el código, vos lo bajás, rezás, y tratás de que corra. El paper era de 2019. El código, en TensorFlow 1.x. El quilombo que me armé con las versiones, los grafos estáticos, el tf.Session(), los placeholder... perdí medio día. Después encontré una reimplementación no oficial en PyTorch. Funcionó en quince minutos. Esa diferencia — la de sentir que el framework trabaja con vos y no contra vos — es exactamente lo que voy a intentar explicar en este post.

PyTorch no necesita presentación en 2025, pero merece una explicación honesta. Porque hay una diferencia entre saber que algo existe y entender por qué ganó.

Qué hace

PyTorch es una librería open source de machine learning desarrollada principalmente por Meta AI (antes Facebook AI Research). Está basada en Torch, una librería de cómputo científico que venía del mundo Lua, y desde 2016 vive en Python como ciudadano de primera clase.

El diferencial técnico que lo define es su enfoque define-by-run (también llamado grafo dinámico o eager execution). A diferencia del TensorFlow original que construía un grafo de computación estático y después lo ejecutaba, PyTorch construye el grafo mientras ejecuta. Esto puede sonar como un detalle de implementación, pero en la práctica cambia todo: podés usar un debugger normal, podés poner un print() en el medio de tu red neuronal y ver qué está pasando, podés tener lógica condicional real con if y for de Python.

import torch
import torch.nn as nn

# Definición de una red neuronal simple — todo es Python puro, sin magia
class RedSimple(nn.Module):
    def __init__(self):
        super().__init__()
        # Una capa oculta de 128 neuronas, una de salida con 10 clases
        self.capas = nn.Sequential(
            nn.Linear(784, 128),  # entrada: imagen 28x28 aplanada
            nn.ReLU(),            # función de activación
            nn.Linear(128, 10)    # salida: 10 clases (ej: dígitos MNIST)
        )

    def forward(self, x):
        return self.capas(x)

# Instanciamos la red y la mandamos a GPU si está disponible
dispositivo = torch.device("cuda" if torch.cuda.is_available() else "cpu")
red = RedSimple().to(dispositivo)

# El autograd calcula los gradientes automáticamente — backprop gratis
print(red)

El soporte nativo de GPU vía CUDA es transparente: movés un tensor con .to(device) y listo. El sistema de autograd calcula los gradientes automáticamente para cualquier operación que hagas sobre tensores, lo que significa que implementar backpropagation custom es sorprendentemente manejable.

El ecosistema que creció alrededor es monumental: torchvision para computer vision, torchaudio para procesamiento de audio, HuggingFace Transformers (que corre principalmente sobre PyTorch), PyTorch Lightning para estructurar el training loop sin volverse loco. Si buscás la implementación oficial de algún paper de los últimos cinco años, con alta probabilidad está en PyTorch.

# Ejemplo de training loop básico — esto es lo que Lightning después abstrae
optimizer = torch.optim.Adam(red.parameters(), lr=1e-3)
criterio = nn.CrossEntropyLoss()

for epoch in range(10):
    for imagenes, etiquetas in dataloader:  # dataloader itera el dataset
        imagenes = imagenes.to(dispositivo)
        etiquetas = etiquetas.to(dispositivo)

        optimizer.zero_grad()          # limpiamos gradientes del paso anterior
        predicciones = red(imagenes)   # forward pass
        loss = criterio(predicciones, etiquetas)  # calculamos error
        loss.backward()                # backward pass — autograd en acción
        optimizer.step()               # actualizamos pesos

    print(f"Epoch {epoch+1}, Loss: {loss.item():.4f}")

Por qué está en la lista

Apareció en 6 awesome lists independientes. Eso no es casualidad. El sistema de curación que usamos en esta serie trata esa señal de consenso como un indicador fuerte: cuando comunidades distintas, con criterios distintos, coinciden en recomendar la misma herramienta, algo está pasando.

Lo que está pasando con PyTorch es que ganó la guerra de los frameworks de deep learning — y la ganó de la manera más convincente posible: ganándola primero en investigación y después filtrándose a producción. Hoy la mayoría de los papers en NeurIPS, ICML y similares publican código en PyTorch. HuggingFace, que es básicamente el hub de modelos más importante del mundo, está construido sobre PyTorch. Eso genera un flywheel brutal: más investigadores → más papers → más código → más adopción → más investigadores.

Comparado con TensorFlow (que cubrimos en el post anterior), PyTorch tiene una API más pythónica y una experiencia de debugging significativamente más humana. TensorFlow recuperó terreno con Keras y eager execution, pero la percepción de la comunidad investigadora ya estaba formada. Para equipos que construyen y experimentan rápido, PyTorch es la opción que tiene menos fricción.

El respaldo de Meta garantiza recursos de desarrollo serios. No es un proyecto de hobby con riesgo de abandono — es infraestructura crítica para uno de los jugadores más grandes del ecosistema AI.

Cuándo NO usarlo

Primero y principal: si no estás haciendo deep learning, probablemente no lo necesitás. Para clasificación, regresión, árboles de decisión, clustering — scikit-learn te va a dar lo mismo con un décimo de la complejidad. PyTorch es un cañón, y no todos los problemas son un elefante.

Segundo: el deployment a producción históricamente fue el talón de Aquiles. TensorFlow con TFLite o TensorFlow Serving tiene una historia más larga y más rodada para servir modelos en edge o en APIs de alta escala. PyTorch mejoró esto con TorchScript (para serializar modelos) y ONNX (para exportar a otros runtimes), pero esas herramientas agregan fricción real — y si venís del post de m2cgen, sabés que a veces la solución más elegante al deployment es no llevar el framework a producción en absoluto.

Tercero: el consumo de memoria en GPU para modelos grandes es un mundo aparte. Sin conocimiento de las internals — gradient checkpointing, mixed precision, data parallelism — es fácil quedarse sin VRAM y no entender por qué.

Cierre

PyTorch es de esas herramientas que tiene el consenso de la comunidad no por marketing sino porque resolvió un problema real mejor que la competencia. El grafo dinámico, la API pythónica, el ecosistema que creció alrededor — todo apunta en la misma dirección. Si vas a meterte en deep learning, es el punto de partida más razonable que existe hoy.

Esta fue la entrega #5 de Awesome Curated: The Tools. La serie sigue — cada tool que aparece acá pasó por un proceso de curación que combina señal de múltiples awesome lists, análisis de IA y veredicto humano mío. Si querés ver el recorrido completo desde Docker hasta acá, arrancá desde el primer post. La próxima herramienta ya está en el pipeline.

Este artículo fue publicado originalmente en juanchi.dev

TensorFlow: the ML elephant that's still standing

Juan Torchia — Tue, 23 Jun 2026 12:01:30 +0000

This is post #4 in the Awesome Curated: The Tools series — where I do deep dives on the tools that pass the filter of our automated curation system. If you landed here directly, you might also want to check out how m2cgen lets you export ML models without shipping Python to production, because it connects pretty directly to what we're talking about today.

I was in an architecture meeting a few months ago. A team wanted to tear down their ML production stack and migrate everything to PyTorch because "TensorFlow is old and nobody uses it anymore." The main argument was that all the recent papers use PyTorch. I asked: where does the model run today? On a server on Google Cloud. Are there mobile endpoints? Yes — an iOS and Android app. How much traffic? Millions of requests per day.

I told them migrating wasn't necessarily a bad idea, but could they walk me through how much effort it would take to rewrite the deployment pipeline, the production serving layer, and the compiled TFLite model running on those mobile devices. Silence. The migration makes technical sense in an ideal world where you have six months and zero users waiting. In the real world, TensorFlow is still the answer when deployment matters more than the elegance of your training code.

And that's exactly what puts it here, on the list.

What it does

TensorFlow is Google's open-source machine learning framework. It started as a C++ library with Python bindings, and that's not a minor detail — the performance core is written in C++ and CUDA, and the Python API is essentially a very powerful wrapper over that. Today it has over 185k GitHub stars, which makes it one of the most starred repos on the entire platform.

The core proposition is: you build a computational graph that describes your model, and TF optimizes and executes it. In TF2 this got a lot friendlier with eager execution on by default (you can run operations line by line, just like in PyTorch), but the real power kicks in when you use @tf.function to compile functions into optimized graphs:

import tensorflow as tf

# Define the model — I'm using Keras which ships built into TF2
model = tf.keras.Sequential([
    tf.keras.layers.Dense(128, activation='relu', input_shape=(784,)),
    tf.keras.layers.Dropout(0.2),  # Regularization to prevent overfitting
    tf.keras.layers.Dense(10, activation='softmax')  # 10 output classes
])

# Compile with optimizer and loss function
model.compile(
    optimizer='adam',
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy']
)

# Training — X_train and y_train are your data
model.fit(X_train, y_train, epochs=10, validation_split=0.2)

But where TF really shines is the deployment ecosystem. TFLite converts trained models into optimized versions for mobile and edge devices — with quantization that shrinks model size from megabytes to kilobytes without losing too much accuracy. TensorFlow Serving is a production model server that scales horizontally, handles versioning, and delivers extremely low latencies. TensorFlow.js runs models in the browser. It's an entire ecosystem, not just a training library.

# Export to TFLite for mobile deployment
converter = tf.lite.TFLiteConverter.from_keras_model(model)

# Dynamic quantization — reduces size without retraining
converter.optimizations = [tf.lite.Optimize.DEFAULT]

# Convert — the output is a .tflite file that goes straight to iOS/Android
tflite_model = converter.convert()

# Save to disk
with open('optimized_model.tflite', 'wb') as f:
    f.write(tflite_model)

# This file is typically 3-10x smaller than the original model
# and runs without needing Python on the target device
print(f'TFLite model size: {len(tflite_model) / 1024:.1f} KB')

Why it made the list

The curation system picked it up in 6 independent awesome lists. That doesn't happen because of hype — it happens because 6 different communities, with different criteria, all reached the same conclusion: this is a tool you can't ignore. And the verdict from both the AI analysis and my own review was GEM, which in our system means exactly what it sounds like: something with real, lasting value.

What differentiates TF from PyTorch in this context isn't which one trains models better — in that game, honestly, PyTorch won the cultural war, especially in research. What sets TF apart is the deployment story. TFLite has no direct equivalent in the PyTorch ecosystem that's anywhere near as mature for production mobile use. TorchScript exists, but if you've ever tried to integrate a PyTorch model into a native iOS app you already know the pain compared to TFLite. TensorFlow Serving spent years handling brutal production workloads inside Google before it was ever open-sourced — that translates into a level of robustness you simply can't manufacture overnight.

The other factor is Google Cloud. If your infrastructure lives there, the native integration with Vertex AI, Cloud ML Engine, and the rest of the GCP ecosystem is a real multiplier. It's not ideological lock-in — it's architectural pragmatism.

When NOT to use it

If you're learning ML from scratch or doing research, PyTorch (github.com/pytorch/pytorch) will make your life much simpler. The API is more Pythonic, debugging is more intuitive because everything runs in eager mode by default, and the research community lives there — which means new papers come with PyTorch code, not TF. The historical baggage of TF1 vs TF2 still haunts Stack Overflow: you find contradictory answers because people mix versions without clarifying which is which. It's disorienting.

I wouldn't use it for small projects where deployment is just a normal Python web server either. In that case, you can train with whatever you want and export with m2cgen if the model is simple enough, or serve with FastAPI + pickle if you don't need scale. TF adds real complexity — use it when the problem justifies it.

And if your team has nobody with TF experience, the onboarding cost for a new project probably isn't worth it unless edge or mobile deployment is a concrete requirement from day zero.

TF is still standing, and there are reasons for that

What pushed me to confirm the human GEM verdict is this: TensorFlow isn't on 6 lists because it's trending. It's there because it solves production problems that others don't solve as well. It's the kind of tool you won't pick out of enthusiasm — you'll pick it out of necessity. And when you need it, you'll be glad it exists and that it's spent a decade getting battle-tested.

This is post #4 in Awesome Curated: The Tools. The series continues — every tool that shows up here has been through a community signal filter, AI analysis, and a human verdict before making the cut. If you're particularly interested in the ML angle, the post on m2cgen pairs really well with this one: it's exactly the other side of the coin, when the model is already trained and you need to get Python out of your production stack entirely.

This article was originally published on juanchi.dev

TensorFlow: el elefante de ML que sigue en pie

Juan Torchia — Tue, 23 Jun 2026 12:01:26 +0000

Este es el post #4 de la serie Awesome Curated: The Tools — donde hago deep dives en las herramientas que pasan el filtro de nuestro sistema de curación automático. Si llegaste directo acá, quizás te interese ver también cómo m2cgen te permite exportar modelos de ML sin llevar Python a producción, que tiene bastante que ver con lo que vamos a hablar hoy.

Estaba en una reunión de arquitectura hace unos meses. Un equipo quería tirar abajo su stack de ML en producción y migrar todo a PyTorch porque "TensorFlow es viejo y nadie lo usa". El argumento principal era que en los papers más recientes todo el mundo usa PyTorch. Les pregunté: ¿dónde corre el modelo hoy? En un servidor con Google Cloud. ¿Hay endpoints móviles? Sí, una app iOS y Android. ¿Cuánto tráfico? Millones de requests por día.

Les dije que no era una mala idea migrar, pero que me explicaran cuánto esfuerzo tenían para reescribir la pipeline de deployment, el serving en producción y el modelo compilado para TFLite en los móviles. Silencio. La migración técnicamente tiene sentido en un mundo ideal donde tenés seis meses y cero usuarios esperando. En el mundo real, TensorFlow sigue siendo la opción cuando el deployment importa más que la elegancia del código de entrenamiento.

Y eso es exactamente lo que lo pone acá, en la lista.

Qué hace

TensorFlow es el framework de machine learning open-source de Google. Arrancó como una librería de C++ con bindings para Python, y eso no es un detalle menor — el core de rendimiento está escrito en C++ y CUDA, y la API de Python es básicamente un wrapper muy poderoso sobre eso. Hoy tiene más de 185k estrellas en GitHub, lo que lo convierte en uno de los repos más starreados de toda la plataforma.

La propuesta central es: construís un grafo computacional que describe tu modelo, y TF lo optimiza y ejecuta. En TF2 esto se volvió más amigable con eager execution por default (podés ejecutar operaciones línea a línea como en PyTorch), pero el poder real está cuando usás @tf.function para compilar funciones en grafos optimizados:

import tensorflow as tf

# Definimos el modelo — acá uso Keras que viene integrado en TF2
model = tf.keras.Sequential([
    tf.keras.layers.Dense(128, activation='relu', input_shape=(784,)),
    tf.keras.layers.Dropout(0.2),  # Regularización para evitar overfitting
    tf.keras.layers.Dense(10, activation='softmax')  # 10 clases de salida
])

# Compilamos con optimizador y función de pérdida
model.compile(
    optimizer='adam',
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy']
)

# Entrenamiento — X_train e y_train son tus datos
model.fit(X_train, y_train, epochs=10, validation_split=0.2)

Pero donde TF realmente brilla es en el ecosistema de deployment. TFLite convierte modelos entrenados en versiones optimizadas para móviles y dispositivos edge — con cuantización que reduce el tamaño del modelo de megabytes a kilobytes sin perder demasiada precisión. TensorFlow Serving es un servidor de modelos en producción que escala horizontal, maneja versioning y tiene latencias bajísimas. TensorFlow.js corre modelos en el browser. Es un ecosistema entero, no solo una librería de entrenamiento.

# Exportar a TFLite para deployment en móvil
converter = tf.lite.TFLiteConverter.from_keras_model(model)

# Cuantización dinámica — reduce tamaño sin reentrenar
converter.optimizations = [tf.lite.Optimize.DEFAULT]

# Convertimos — el resultado es un archivo .tflite que va directo a iOS/Android
tflite_model = converter.convert()

# Lo guardamos al disco
with open('modelo_optimizado.tflite', 'wb') as f:
    f.write(tflite_model)

# Este archivo pesa típicamente 3-10x menos que el modelo original
# y corre sin necesidad de Python en el dispositivo final
print(f'Tamaño del modelo TFLite: {len(tflite_model) / 1024:.1f} KB')

Por qué está en la lista

El sistema de curación lo detectó en 6 awesome lists independientes. Eso no pasa por hype — pasa porque 6 comunidades distintas, con criterios distintos, llegaron a la misma conclusión: es una herramienta que no podés ignorar. Y el veredicto tanto del análisis de IA como el mío fue GEM, que en nuestro sistema significa exactamente lo que parece: algo que tiene valor real y duradero.

Lo que lo diferencia de PyTorch en este contexto no es quién entrena mejor los modelos — en ese juego, honestamente, PyTorch ganó la batalla cultural, especialmente en investigación. Lo que diferencia a TF es el deployment story. TFLite no tiene equivalente directo en el ecosistema PyTorch que sea tan maduro para producción móvil. TorchScript existe, pero si alguna vez intentaste integrar un modelo PyTorch en una app iOS nativa vas a saber el dolor que es comparado con TFLite. TensorFlow Serving lleva años corriendo cargas de producción brutal en Google antes de ser open-source — eso se traduce en robustez que no se consigue de un día para el otro.

El otro factor es Google Cloud. Si tu infraestructura vive ahí, la integración nativa con Vertex AI, Cloud ML Engine y el resto del ecosistema GCP es un multiplicador real. No es lock-in ideológico — es pragmatismo de arquitectura.

Cuándo NO usarlo

Si estás aprendiendo ML desde cero o haciendo investigación, PyTorch (github.com/pytorch/pytorch) te va a hacer la vida mucho más simple. La API es más pythónica, el debugging es más intuitivo porque todo corre en eager mode por default, y la comunidad investigadora está ahí — lo que significa que los papers nuevos tienen código en PyTorch, no en TF. La deuda histórica de TF1 vs TF2 todavía se siente en Stack Overflow: encontrás respuestas contradictorias porque mezclan versiones sin aclarar cuál es cuál. Eso marea.

Tampoco lo usaría para proyectos pequeños donde el deployment es un servidor web normal con Python. En ese caso, podés entrenar con lo que quieras y exportar con m2cgen si el modelo es suficientemente simple, o servir con FastAPI + pickle si no necesitás escala. TF agrega complejidad real — usala cuando el problema lo justifica.

Y si tu equipo no tiene nadie con experiencia en TF, el costo de onboarding para un proyecto nuevo probablemente no vale la pena salvo que el deployment en edge o móvil sea un requerimiento concreto desde el día cero.

TF sigue en pie, y hay razones para eso

Lo que me llevó a confirmar el GEM humano es esto: TensorFlow no está en 6 listas porque esté de moda. Está porque resuelve problemas de producción que otros no resuelven igual de bien. Es el tipo de herramienta que no vas a elegir por entusiasmo sino por necesidad — y cuando la necesitás, vas a estar contento de que existe y de que lleva una década siendo battle-tested.

Este es el post #4 de Awesome Curated: The Tools. La serie sigue — cada herramienta que aparece pasó por un filtro de señal de comunidad, análisis de IA y veredicto humano antes de llegar acá. Si te interesa el tema de ML en particular, el post sobre m2cgen cierra muy bien con este: es exactamente la otra cara de la moneda, cuando el modelo ya está entrenado y necesitás sacarte Python de encima en producción.

Este artículo fue publicado originalmente en juanchi.dev

Rate limiting in Next.js: what to protect before picking a library

Juan Torchia — Mon, 22 Jun 2026 14:32:17 +0000

Rate limiting in Next.js: what to protect before picking a library

There's a pattern I keep seeing in web projects: someone reads about credential stuffing, opens the terminal, and runs npm install @upstash/ratelimit. Fifteen minutes later there's a middleware capping 10 requests per IP per minute across all routes. The problem isn't the library — it's a good one — the problem is that configuration protects a profile image API with the same intensity as a login endpoint, and it blocks a legitimate user behind a corporate NAT before they ever get to authenticate.

My thesis is simple: rate limiting isn't a dependency, it's an abuse policy. And a policy without a defined asset, expected abuse pattern, and false positive cost isn't security — it's noise with latency.

Before installing anything, there are three questions you need to answer. This post is about those questions.

Rate limiting in Next.js web apps: the missing mental model

When we think about rate limiting, we tend to think "how many requests per second." But that confuses the mechanism with the goal. The real goal is making certain abuse patterns expensive for the attacker without making them expensive for the legitimate user.

OWASP covers this in their Authentication Cheat Sheet from the authentication angle: progressive failed attempt counting, temporary lockout, user notification. What it doesn't say — and this is equally important — is what not to block. That part you have to decide yourself.

The framework I find most honest has four columns:

Question	What you're trying to define
What asset are you protecting?	Specific endpoint, resource, flow
What abuse pattern do you expect?	Credential stuffing, scraping, layer-7 DDoS, form spam
What does a false positive cost you?	Blocked user, lost conversion, wrong support ticket
How are you going to observe it?	Metrics, logs, alerts, hit/block differentiation

Without all four columns filled in, any configuration you pick is a guess. It might work. It might also block real users in production with nobody noticing until the complaint comes in.

Where the standard recipe breaks

Global rate limiting middleware in Next.js has a legitimate use case: protecting public routes from mass scraping or brute force on login. But it comes with costs that tutorials tend to skip.

The shared IP problem. If you limit by IP and the user is behind a corporate proxy or a university NAT, dozens or hundreds of different users share the same address. One active user can burn through everyone else's budget. This isn't an edge case — it's the normal scenario for any B2B app.

The scope-too-wide problem. A middleware in middleware.ts that intercepts /(.*) applies the limit to /api/auth/login, /api/profile/avatar, /api/search, and /sitemap.xml equally. The cost of a false positive on login is very different from the cost of one on image assets. Mixing them gives you apparent protection, not real protection.

The missing observability problem. How many requests did you block today? How many were legitimate? Without that distinction, you can't calibrate. It's not that rate limiting is bad — it's that without observability, you don't know if it's working or if it's causing damage.

A more defensive pattern in Next.js App Router looks like this:

// middleware.ts — selective rate limiting by route, not global
import { NextRequest, NextResponse } from 'next/server'

// Explicit list of routes that justify protection
const PROTECTED_ROUTES = ['/api/auth/login', '/api/auth/register', '/api/contact']

export function middleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname

  // Only apply on routes we've defined as critical assets
  if (!PROTECTED_ROUTES.some((route) => pathname.startsWith(route))) {
    return NextResponse.next()
  }

  // The counting mechanism goes here (Upstash, Redis, etc.)
  // The point: this block has explicit scope, not implicit
  return NextResponse.next()
}

export const config = {
  matcher: ['/api/auth/:path*', '/api/contact/:path*'],
}

The difference isn't in the library. It's that the matcher is explicit. If you add /api/upload tomorrow, it doesn't inherit the limit by accident — you have to consciously decide whether to protect it.

The decision matrix before choosing a mechanism

This is the part I most want to share because it's the part most people skip. Before choosing between Redis + Upstash, a stateless token middleware, or your cloud provider's built-in rate limiting, you need to answer:

What asset are you protecting?

Not all routes carry the same risk under abuse. One way to think about it:

High sensitivity: login, registration, password reset, payment endpoints, email sending. Abuse here has direct consequences: compromised accounts, real costs in third-party services, spam.
Medium sensitivity: search, public listings, internal APIs. Abuse here is more about scraping or overload, not account takeover.
Low sensitivity: static assets, UI routes, sitemap. Protecting these with rate limiting adds latency without reducing real risk.

What abuse pattern do you expect?

This changes the mechanism, not just the threshold:

Credential stuffing on login: you want a limit by IP and by username, with progressive backoff. OWASP specifically recommends against permanent account lockout to prevent attackers from using that as a DoS vector against legitimate users.
Scraping of listings: IP limit with a sliding window. Here throughput matters, not failed attempts.
Contact form spam: IP limit + honeypot + origin validation. Rate limiting alone isn't enough if the form doesn't have a CSRF token.

What does a false positive cost you?

This is the most uncomfortable question because it forces you to put a number on something that feels abstract. Some questions to calibrate:

How much is an erroneously blocked user session worth? (support cost, lost conversion)
How many legitimate users share an IP in your target market segment?
Is there a low-friction recovery path if the rate limit fires incorrectly?

If the false positive cost is high and the asset is critical, the threshold needs to be conservative on blocking but generous on recovery time.

How are you going to observe it?

A rate limiter without metrics is a black box. The minimum you need:

// Minimal logging example when rejecting a request
// Adapt to your own logging system (pino, winston, structured stdout)
function logRateLimitEvent(request: NextRequest, result: 'blocked' | 'allowed') {
  const event = {
    timestamp: new Date().toISOString(),
    route: request.nextUrl.pathname,
    ip: request.ip ?? 'unknown',
    result,
    // Never log auth headers or body here
  }
  console.log(JSON.stringify(event))
}

With this, you can at least run a daily query: how many blocked, on which routes, at what time? Without it, the policy is opaque.

Common mistakes and their real costs

Using a global limit as a substitute for analysis. "10 requests per minute per IP across the whole domain" sounds reasonable until a bot uses 10,000 rotating IPs and gets through anyway, while a real user on a corporate VPN gets locked out.

Trusting IP as a unique identifier. IPv4 with NAT and CDNs makes IP a noisy identifier. For authenticated routes, the identifier should be the user ID, not the IP. For public routes, IP is what you've got — but with all the limitations that implies.

Not differentiating between 429 Too Many Requests with and without Retry-After. If you block a request and don't return a Retry-After header, the client (and the user) has no idea when to retry. OWASP calls out backoff as an explicit mechanism; the header is how the server communicates it.

// Correct response with recovery information
return new NextResponse('Too many attempts. Please wait a moment.', {
  status: 429,
  headers: {
    'Retry-After': '60', // seconds until they can retry
    'X-RateLimit-Reset': String(Math.floor(Date.now() / 1000) + 60),
  },
})

Adding rate limiting without checking if an upstream layer already exists. Railway, Vercel, and Cloudflare all have their own rate limiting controls. Adding your own in middleware without knowing what the upstream is doing can create unexpected behavior — or simply duplicate work without reducing additional risk.

Limits of this guide: what you can't conclude without your own data

I need to be direct about what this guide does not give you:

There are no universal thresholds. "10 requests per minute" for login might be too low for an app with mobile users reconnecting frequently, and too high for a B2B app where a legitimate login rarely repeats more than twice in a row. The right number comes from observing your actual users' real behavior.
There's no evidence that rate limiting alone prevents account takeover. OWASP treats it as a complementary control, not the main defense. Without MFA, without compromised credential detection (haveibeenpwned.com has a public API for this), rate limiting on login slows down simple brute force but not sophisticated credential stuffing with rotating IPs.
You can't calibrate the false positive without logs. Whatever number you pick today is a hypothesis. Calibration comes from observing how many legitimate requests approach the threshold under normal conditions.

This connects to something I covered in the post on OAuth Scope Creep: security controls have to be designed from specific risk, not from a generic recipe. And in OWASP LLM Top 10 for agents I landed on a similar conclusion: the guide gives you the framework, but calibration comes from your own data.

FAQ: Rate limiting in Next.js

Is Upstash the only option for rate limiting in Next.js with App Router?
No. Upstash with Redis is popular because it works well in serverless environments (Vercel, Railway with Workers), but you can implement rate limiting with any shared storage: your own Redis, Memcached, or even a database if the volume allows. The choice depends on tolerated latency and your deployment model. If the middleware runs on the edge, you need something with low latency that's compatible with the edge runtime (no native Node.js).

Does it make sense to rate limit static asset routes?
In most cases, no. Static assets (/_next/static/, public images) have low abuse cost and high false positive cost (real users hammer them heavily during page loads). CDN or hosting provider rate limiting already covers this better than custom middleware.

How do I handle users behind NAT or a corporate VPN?
For authenticated routes, use the user ID as the limit identifier, not the IP. For public routes, you can combine IP with header fingerprinting or use more generous limits paired with anomaly detection (many failed attempts from the same IP). There's no perfect solution here — it's a trade-off between blocking precision and false positive cost.

What does the server return when rate limiting fires? Does the message matter?
More than you'd think. A 429 without Retry-After leaves the client with no information on when to retry. A message that's too specific ("blocked due to excessive login attempts") can hand the attacker information about the mechanism. The reasonable approach: 429 with Retry-After and a generic user-facing message ("Too many requests, please wait a moment").

Does rate limiting in Next.js middleware also cover Server Actions?
It depends on how you configure it. Server Actions generate POST requests to the same page URL, not a separate API route. If the middleware matcher doesn't cover those routes, Server Actions won't have the limit applied. Check the matcher explicitly if you want to protect forms using Server Actions.

Does Railway have native rate limiting that replaces middleware?
Railway doesn't have native application-level rate limiting (as of when I'm writing this). It has infrastructure-level protection, but no granular control per route or per user. For application-specific abuse logic, you need to implement it yourself. If you're running Cloudflare in front of Railway, Cloudflare does offer per-route rate limiting that can be enough for simple cases.

Conclusion: the policy before the library

Thirty years in tech taught me that the most expensive mistakes aren't the ones that break the system — they're the ones that give you the feeling of control without actually having it. A rate limiting middleware installed without a defined policy falls squarely in that category: the 200 OK from the deploy masks the fact that you don't know what you're protecting, against what, with what threshold, or whether you're silently damaging legitimate users.

My practical recommendation: before opening any library, fill in the four columns of the matrix. Asset, expected abuse, false positive cost, observability. If you can't fill them in, you don't have a policy — you have configuration by imitation.

Then, yes, pick the mechanism that fits your stack. Upstash for serverless, your own Redis if you have the control, the cloud provider's rate limiting if the case is simple. The technology is the easy part. The hard part is the design decision that comes before it.

The concrete next step: take a single critical route in the app — preferably login or registration — and answer the four questions for that route alone. Not the whole system. One route, four answers, one threshold calibrated with logs. That's more useful than a global middleware configured with numbers someone copied from a tutorial.

Sources

OWASP Authentication Cheat Sheet — defensive authentication and abuse controls

This article was originally published on juanchi.dev

Rate limiting en Next.js: qué proteger antes de elegir una librería

Juan Torchia — Mon, 22 Jun 2026 14:32:09 +0000

Rate limiting en Next.js: qué proteger antes de elegir una librería

Hay un patrón que se repite en proyectos web: alguien lee sobre credential stuffing, abre la terminal y corre npm install @upstash/ratelimit. Quince minutos después, hay un middleware que limita a 10 requests por IP por minuto sobre todas las rutas. El problema no es la librería —es buena— el problema es que esa configuración protege una API de imágenes de perfil con el mismo rigor que un endpoint de login, y bloquea a un usuario legítimo detrás de un NAT corporativo antes de que llegue a autenticarse.

Mi tesis es simple: rate limiting no es una dependencia, es una política de abuso. Y una política sin definición del activo, del abuso esperado y del costo del falso positivo no es seguridad; es ruido con latencia.

Antes de instalar nada, hay tres preguntas que necesitás responder. Este post es sobre esas preguntas.

Rate limiting en aplicaciones web Next.js: el modelo mental que falta

Cuando pensamos en rate limiting, tendemos a pensar en "cuántos requests por segundo". Pero eso confunde el mecanismo con el objetivo. El objetivo real es hacer que ciertos patrones de abuso sean costosos para el atacante sin hacerlos costosos para el usuario legítimo.

OWASP lo plantea en su Authentication Cheat Sheet desde el ángulo de autenticación: cuenta progresiva de intentos fallidos, lockout temporal, notificación al usuario. Lo que no dice —y es igual de importante— es qué no bloquear. Esa parte la tenés que decidir vos.

El marco que me parece más honesto tiene cuatro columnas:

Pregunta	Lo que buscás definir
¿Qué activo protegés?	Endpoint específico, recurso, flujo
¿Qué patrón de abuso esperás?	Credential stuffing, scraping, DDoS de capa 7, spam de formularios
¿Cuánto cuesta el falso positivo?	Usuario bloqueado, conversión perdida, soporte incorrecto
¿Cómo lo vas a observar?	Métricas, logs, alertas, diferenciación hit/block

Sin esas cuatro columnas llenas, cualquier configuración que elijas es una conjetura. Puede funcionar. También puede bloquear usuarios reales en producción sin que nadie se entere hasta que llega el reclamo.

Dónde se rompe la receta estándar

El middleware global de rate limiting en Next.js tiene un caso de uso legítimo: proteger rutas públicas de scraping masivo o de ataques de fuerza bruta sobre login. Pero viene con costos que los tutoriales suelen omitir.

El problema de la IP compartida. Si limitás por IP y el usuario está detrás de un proxy corporativo o un NAT universitario, decenas o cientos de usuarios distintos comparten la misma dirección. Un solo usuario activo puede consumir el budget del resto. No es un edge case: es el escenario normal de cualquier app B2B.

El problema del scope demasiado ancho. Un middleware en middleware.ts que intercepta /(.*) aplica el límite a /api/auth/login, /api/profile/avatar, /api/search y /sitemap.xml por igual. El costo de un falso positivo en login es muy distinto al de un falso positivo en imágenes. Mezclarlos te da protección aparente, no real.

El problema de la observabilidad ausente. ¿Cuántos requests bloqueaste hoy? ¿Cuántos eran legítimos? Sin esa distinción, no podés calibrar. No es que rate limiting sea malo —es que sin observabilidad, no sabés si está funcionando ni si está dañando.

Un patrón más defensivo en Next.js App Router se ve así:

// middleware.ts — rate limiting selectivo por ruta, no global
import { NextRequest, NextResponse } from 'next/server'

// Lista explícita de rutas que justifican protección
const RUTAS_PROTEGIDAS = ['/api/auth/login', '/api/auth/register', '/api/contact']

export function middleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname

  // Solo aplicar en rutas que definimos como activos críticos
  if (!RUTAS_PROTEGIDAS.some((ruta) => pathname.startsWith(ruta))) {
    return NextResponse.next()
  }

  // El mecanismo de conteo va aquí (Upstash, Redis, etc.)
  // Lo importante: este bloque tiene scope explícito, no implícito
  return NextResponse.next()
}

export const config = {
  matcher: ['/api/auth/:path*', '/api/contact/:path*'],
}

La diferencia no está en la librería. Está en que el matcher es explícito. Si mañana agregás /api/upload, no hereda el límite por accidente: tenés que decidir conscientemente si lo protegés.

La matriz de decisión antes de elegir el mecanismo

Esta es la parte que más me interesa compartir porque es la que más se saltea. Antes de elegir entre Redis + Upstash, un middleware stateless con tokens, o el rate limiting del proveedor de nube, necesitás responder:

¿Qué activo protegés?

No todas las rutas tienen el mismo valor bajo abuso. Una forma de pensar en esto:

Alta sensibilidad: login, registro, reset de contraseña, endpoints de pago, envío de emails. El abuso acá tiene consecuencias directas: cuentas comprometidas, costo real en servicios de terceros, spam.
Sensibilidad media: búsqueda, listados públicos, APIs internas. El abuso acá es más de scraping o sobrecarga, no de account takeover.
Baja sensibilidad: assets estáticos, rutas de UI, sitemap. Protegerlos con rate limiting agrega latencia sin reducir riesgo real.

¿Qué patrón de abuso esperás?

Esto cambia el mecanismo, no solo el umbral:

Credential stuffing en login: querés límite por IP y por username, con backoff progresivo. OWASP recomienda específicamente no lockear cuentas de forma permanente para evitar que el atacante use eso como vector de DoS contra usuarios legítimos.
Scraping de listados: límite por IP con ventana deslizante. Acá sí importa el throughput, no los intentos fallidos.
Spam de formularios de contacto: límite por IP + honeypot + validación de origen. Rate limiting solo no alcanza si el formulario no tiene CSRF token.

¿Cuánto cuesta el falso positivo?

Esta es la pregunta que más incomoda porque obliga a poner número a algo que parece abstracto. Algunas preguntas para calibrar:

¿Cuánto vale una sesión de usuario bloqueada por error? (costo de soporte, conversión perdida)
¿Cuántos usuarios legítimos comparten IP en el segmento de mercado propio?
¿Hay algún mecanismo de recuperación sin fricción si el rate limit se activa equivocado?

Si el costo del falso positivo es alto y el activo es crítico, el umbral tiene que ser conservador en el bloqueo pero generoso en el tiempo de recuperación.

¿Cómo lo vas a observar?

Un rate limiter sin métricas es un black box. Lo mínimo que necesitás:

// Ejemplo de logging mínimo al rechazar un request
// Adaptar al sistema de logs propio (pino, winston, stdout estructurado)
function logRateLimitEvent(request: NextRequest, resultado: 'bloqueado' | 'permitido') {
  const evento = {
    timestamp: new Date().toISOString(),
    ruta: request.nextUrl.pathname,
    ip: request.ip ?? 'desconocida',
    resultado,
    // Nunca logear headers de autenticación ni body acá
  }
  console.log(JSON.stringify(evento))
}

Con esto, al menos podés hacer una query diaria: ¿cuántos bloqueados, en qué rutas, a qué hora? Sin eso, la política es opaca.

Errores comunes y sus costos reales

Usar el límite global como sustituto del análisis. "10 requests por minuto por IP en todo el dominio" suena razonable hasta que un bot usa 10.000 IPs rotativas y pasa igual, mientras que un usuario real con VPN corporativa se queda afuera.

Confiar en IP como identificador único. IPv4 con NAT y CDNs hacen que la IP sea un identificador ruidoso. Para rutas autenticadas, el identificador debería ser el user ID, no la IP. Para rutas públicas, la IP es lo que tenés, pero con los límites que implica.

No diferenciar entre 429 Too Many Requests con y sin Retry-After. Si bloqueás un request y no devolvés un header Retry-After, el cliente (y el usuario) no sabe cuándo reintentar. OWASP menciona el backoff como mecanismo explícito; el header es la forma en que el servidor lo comunica.

// Respuesta correcta con información de recuperación
return new NextResponse('Demasiados intentos. Esperá un momento.', {
  status: 429,
  headers: {
    'Retry-After': '60', // segundos hasta que puede reintentar
    'X-RateLimit-Reset': String(Math.floor(Date.now() / 1000) + 60),
  },
})

Agregar rate limiting sin revisar si ya existe una capa upstream. Railway, Vercel y Cloudflare tienen controles de rate limiting propios. Agregar uno propio en middleware sin saber qué hace el upstream puede crear comportamientos inesperados —o simplemente duplicar trabajo sin reducir riesgo adicional.

Límites de esta guía: qué no podés concluir sin datos propios

Necesito ser directo sobre lo que esta guía no te da:

No hay umbrales universales. "10 requests por minuto" para login puede ser demasiado bajo para una app con usuarios móviles con reconexión frecuente, y demasiado alto para una app B2B donde un login legítimo rara vez se repite más de dos veces seguidas. El número correcto viene de observar el comportamiento real de los propios usuarios.
No hay evidencia de que rate limiting solo prevenga account takeover. OWASP lo trata como un control complementario, no como la defensa principal. Sin MFA, sin detección de credenciales comprometidas (haveibeenpwned.com tiene una API pública para esto), el rate limiting en login frena fuerza bruta simple pero no credential stuffing sofisticado con IPs rotativas.
No podés calibrar el falso positivo sin logs. Cualquier número que elijas hoy es una hipótesis. La calibración viene de observar cuántos requests legítimos se acercan al umbral en condiciones normales.

Esto conecta con algo que ya traté en el post sobre OAuth Scope Creep: los controles de seguridad tienen que diseñarse desde el riesgo específico, no desde la receta genérica. Y en OWASP LLM Top 10 en agentes llegué a una conclusión parecida: la guía te da el marco, pero la calibración la hacés con los propios datos.

FAQ: Rate limiting en Next.js

¿Upstash es la única opción para rate limiting en Next.js con App Router?
No. Upstash con Redis es popular porque funciona bien en entornos serverless (Vercel, Railway con Workers), pero podés implementar rate limiting con cualquier almacenamiento compartido: Redis propio, Memcached, o incluso una base de datos si el volumen lo permite. La elección depende de la latencia tolerada y del modelo de despliegue. Si el middleware corre en el edge, necesitás algo con latencia baja y compatible con el runtime de edge (sin Node.js nativo).

¿Tiene sentido aplicar rate limiting en rutas de assets estáticos?
En la mayoría de los casos, no. Los assets estáticos (/_next/static/, imágenes públicas) tienen un costo de abuso bajo y un costo de falso positivo alto (usuarios reales los consumen intensivamente en cargas de página). El rate limiting de CDN o del proveedor de hosting ya cubre este caso mejor que un middleware propio.

¿Cómo manejo usuarios detrás de NAT o VPN corporativa?
Para rutas autenticadas, usá el user ID como identificador del límite, no la IP. Para rutas públicas, podés combinar IP con fingerprinting de headers o con límites más generosos acompañados de detección de anomalías (muchos intentos fallidos de la misma IP). No hay solución perfecta acá: es un trade-off entre precisión del bloqueo y costo del falso positivo.

¿Qué devuelve el servidor cuando activo el rate limit? ¿Importa el mensaje?
Importa más de lo que parece. Un 429 sin Retry-After deja al cliente sin información para reintentar. Un mensaje demasiado específico ("bloqueado por exceso de intentos de login") puede dar información al atacante sobre el mecanismo. Lo razonable: 429 con Retry-After y un mensaje genérico orientado al usuario ("Demasiadas solicitudes, esperá un momento").

¿El rate limiting en middleware de Next.js protege también las Server Actions?
Depende de cómo lo configurés. Las Server Actions generan requests POST a la misma URL de la página, no a una ruta de API separada. Si el matcher del middleware no cubre esas rutas, las Server Actions no tienen el límite. Revisá el matcher explícitamente si querés proteger formularios que usan Server Actions.

¿Railway tiene rate limiting nativo que reemplace al del middleware?
Railway no tiene rate limiting de aplicación nativo (al momento de publicar esto). Sí tiene protección a nivel de infraestructura, pero no control granular por ruta o por usuario. Para lógica de abuso específica de la aplicación, necesitás implementarla vos. Si usás un proxy como Cloudflare delante de Railway, Cloudflare sí ofrece rate limiting por ruta que puede ser suficiente para casos simples.

Conclusión: la política antes que la librería

Treinta años de historia con tecnología me enseñaron que los errores más caros no son los que rompen el sistema —son los que dan sensación de control sin tenerlo. Un middleware de rate limiting instalado sin política definida entra en esa categoría: el 200 OK del deploy tapa el hecho de que no sabés qué protegés, contra qué, con qué umbral ni si estás dañando usuarios legítimos en silencio.

Mi recomendación práctica: antes de abrir cualquier librería, completá las cuatro columnas de la matriz. Activo, abuso esperado, costo del falso positivo, observabilidad. Si no podés completarlas, no tenés política —tenés configuración por imitación.

Después sí, elegí el mecanismo que encaje con el stack. Upstash para serverless, Redis propio si tenés el control, el rate limiting del proveedor de nube si el caso es simple. La tecnología es la parte fácil. Lo difícil es la decisión de diseño que va antes.

El próximo paso concreto: tomá una sola ruta crítica de la app —preferentemente login o registro— y respondé las cuatro preguntas para esa ruta sola. No todo el sistema. Una ruta, cuatro respuestas, un límite calibrado con logs. Eso es más útil que un middleware global configurado con números que alguien copió de un tutorial.

Fuentes

OWASP Authentication Cheat Sheet — controles defensivos de autenticación y abuso

Este artículo fue publicado originalmente en juanchi.dev

npm Dependencies: How to Evaluate a Library Before Shipping It to Production

Juan Torchia — Mon, 22 Jun 2026 12:02:41 +0000

npm Dependencies: How to Evaluate a Library Before Shipping It to Production

Back in 2005, when I was 16 and managing the network at a cyber café, I learned something no manual ever taught me: every cable you plugged in was debt. If the vendor for that cable disappeared or changed the connector, the problem was yours. Not the vendor's, not the customer's. Yours. Today, when I look at a package.json with 180 direct dependencies in a TypeScript project, I think exactly the same thing. Every entry in that file is a cable someone is going to have to maintain. And in most cases, that someone is you.

My take is direct: adding an npm dependency isn't just installing code — it's assuming its maintenance, its CVE history, its transitive dependencies, and the exit cost when the library gets abandoned. The question isn't "does it work?" The question is "what happens when it stops working in six months?"

Why Evaluating npm Dependencies Is a Maintenance Decision, Not Just a Security One

The official npm documentation defines a package as "a file or directory described by a package.json" (npm docs). That's all npm guarantees as a platform: that the file exists and has metadata. Nothing about whether the author is still active, whether it has tests, whether the types are correct, or whether you'll be able to upgrade in two years without breaking half the system.

What the official docs don't say — and where people get burned — is that a published package can freeze in time. The author might not have bandwidth, might abandon the project, or might simply never hear about a relevant CVE. And at that point, the debt is yours.

There are three dimensions that matter before installing anything in a TypeScript project with pnpm:

Active maintenance: When was the last commit? Are there PRs that have gone unanswered for months? Any releases in the past year?
Attack surface and types: Does the package ship its own types (@types/) or generate them? How many transitive dependencies does it drag in?
Exit cost: If you need to rip it out tomorrow, how much of your own code changes?

How to Audit a Dependency Before `pnpm add`

The usual recipe is: search on npm, check if it has GitHub stars, install it, done. The problem is that measures popularity, not quality or longevity. Popularity and active maintenance are not the same thing.

Here's the process I use, step by step and fully reproducible:

1. Check the Real State of the Repository

Before installing, open the repo on GitHub and look at:

Last commit on main: if it's been more than 12 months with no activity and it's not a stable utility library (like lodash), that's a signal.
Open issues: Are there bugs sitting unanswered for months? CVEs mentioned but not patched?
CHANGELOG or releases: a serious project has a version history. If it doesn't, the risk surface goes up.

2. Analyze Transitive Dependencies with `pnpm why`

# Install in an isolated test project
pnpm add <package-name>

# See what it brought along
pnpm why <package-name>

# Or a full dependency tree
pnpm list --depth=3

A dependency that looks small can drag in 40 transitive packages. That's not automatically bad — but if two of those 40 have active CVEs, the problem is yours even if your own code never calls them directly.

3. Run a Security Audit From the Start

# Basic audit with npm (works on pnpm projects too)
npm audit

# To see only critical and high vulnerabilities
npm audit --audit-level=high

# If you want the JSON to process it
npm audit --json | jq '.vulnerabilities | to_entries[] | select(.value.severity == "critical")'

npm audit uses the npm Advisory Database to cross-reference installed versions against known CVEs. It's not infallible — there are vulnerabilities that don't have an advisory yet — but it's the minimum reasonable floor before committing to a dependency.

4. Verify TypeScript Types

In a TypeScript project, a dependency without types is guaranteed friction. Check:

# Does the package ship its own types?
cat node_modules/<package>/package.json | grep '"types"'

# Are @types/ available?
npm info @types/<package>

If the package doesn't ship its own types and the @types/ are community-maintained (not by the original author), you have two separate sources of drift. When the package updates and @types/ doesn't, the compiler fails in ways that aren't obvious.

5. Evaluate Exit Cost With Your Own Interface

This is the step that gets skipped the most. The question isn't just "does it work today?" but "how much code do I change if I rip it out tomorrow?"

// Pattern that reduces exit cost:
// Wrap the dependency behind your own interface

// ❌ Using the dependency directly throughout the codebase
import { parse } from 'some-date-lib'
const date = parse('2025-01-15')

// ✅ Abstracting behind your own module
// lib/dates.ts
import { parse as _parse } from 'some-date-lib'

export function parseDate(input: string): Date {
  return _parse(input) // single entry point
}

If the library is spread across 40 different files with no abstraction, removing it costs a major refactor. If it lives in one module, removing it costs an internal implementation swap.

The Most Common Mistakes When Evaluating npm Dependencies

Mistake 1: Confusing Weekly Downloads With Stability

npm download numbers include automatic mirrors, CIs, and pipelines. A library with 2M weekly downloads can have a maintainer who hasn't merged a PR in a year. Downloads are a lagging indicator of past popularity, not a guarantee of future support.

Mistake 2: Ignoring `devDependencies` in Projects With Build Steps

If a vulnerable devDependency is involved in the build (babel, webpack, esbuild, tsx), the code it generates can be compromised. The devDependencies field in package.json separates intent, not risk. If it goes through the compiler, it matters.

Mistake 3: Not Looking at `peerDependencies`

# Check what versions of React/Node the lib expects
npm info <package> peerDependencies

A library that asks for React 17 as a peer in a React 19 project might work — or it might produce silent bugs from duplicate context. Peer conflicts are one of the most common hidden costs in stack upgrades.

Mistake 4: Assuming a Small Package Is Safe

Attack surface isn't proportional to size. The event-stream incident in 2018 showed that a small utility package, transferred to a new maintainer, can become an attack vector. Small doesn't mean harmless. (Source: npm blog on the incident)

This kind of risk connects directly to what I wrote about OAuth Scope Creep: attack surface accumulates at the edges, not the center.

Decision Matrix: Do I Add This Dependency or Not?

Criterion	Green (add it)	Yellow (evaluate further)	Red (avoid or wrap)
Last release	< 6 months	6–18 months	> 18 months with no activity
TypeScript types	Bundled in the package	Active `@types/` aligned with the package	No types or outdated `@types/`
Active CVEs	None	Low severity, no public exploit	Critical or high with no patch
Transitive deps	< 10	10–40	> 40 or deps with CVEs
Exit cost	Easy to wrap	Moderate coupling	Invasive across multiple modules
Active maintainer	Responds to issues/PRs	Slow but responds	No visible activity

If a dependency lands in "Red" on more than two criteria, the right question is: do I actually need this abstraction, or can I implement the specific logic I need in 50 lines of my own code?

When working on projects with pnpm workspaces — like I described in the post about pnpm workspaces and CI on Railway — this evaluation matters twice as much: a problematic dependency in a shared package of the monorepo gets inherited by every app in the workspace.

What This Checklist Can't Guarantee

Being honest about the limits:

It doesn't predict future abandonment: a library with recent releases can get abandoned tomorrow. The checklist measures current state, not future state.
npm audit doesn't cover all vectors: business logic vulnerabilities, sophisticated supply chain attacks, and unreported CVEs don't show up in a standard audit. It's the floor, not the ceiling.
The real exit cost only gets measured in practice: estimating the cost of removing a dependency is a heuristic. Until you actually do it, it's a projection. If the project already has the dependency deeply integrated, the retrospective evaluation is more expensive than the prospective one.
GitHub metrics are indicators, not proof: an archived repository can be stable because it reached feature-complete. A repo with tons of commits can be unstable due to constant refactoring. Context matters.

FAQ: Evaluating npm Dependencies in TypeScript Projects

How many direct dependencies is "too many" in a TypeScript project?

There's no universal number. What is a warning sign is having more than 50–60 direct dependencies without having actively evaluated which ones could be replaced by your own implementations. The criterion isn't the count — it's whether every entry in dependencies has a clear reason that can't be solved in fewer than 100 lines of your own code.

Does pnpm have security advantages over npm or yarn for this kind of audit?

pnpm has a different storage model (content-addressable store) that avoids duplication and makes the dependency tree more predictable. But for CVE audits, npm audit is still the standard tool and works with any lockfile. pnpm's advantage in this context is more about tree predictability than intrinsic security.

What do I do if a dependency has a CVE but no fix is available?

First, evaluate whether the CVE applies to how you're using it. Many CVEs have specific exploitation conditions that may not apply to your context. If it does apply, look for a fork with the fix, replace the dependency, or implement the minimum necessary functionality yourself. Keeping the vulnerable dependency and "noting it for later" is the most comfortable path and the most expensive one in the medium term.

Does it make sense to evaluate devDependencies with the same rigor?

Less rigor, but not zero. Build tools, linters, and compilers that go through the CI pipeline deserve a basic review. A devDependency that's only used on a local machine has less urgency than one that participates in generating the artifact going to production.

How do I evaluate a dependency when it has no visible public repository?

If an npm package doesn't have a public repository linked and has more than a couple of months of existence, the default criterion is don't install it in a serious project. The absence of a public source doesn't imply malice, but it eliminates the possibility of a code audit. Without visible source, the analysis is limited to what the package declares in its package.json — which is incomplete information.

How does this affect maintaining a monorepo with multiple apps?

A problematic dependency in a shared/ package of the monorepo propagates automatically to all consumers. That makes upfront evaluation more important, not less. The cost of a CVE or a breaking change in a shared dependency multiplies by the number of apps in the workspace. It's worth spending more time on shared package dependencies than on ones specific to a single app.

My Take and the Next Concrete Step

Adding an npm dependency is a technical decision with consequences that extend far beyond the current sprint. I'm not saying you should avoid libraries — that would be absurd in an ecosystem where composition is the model. I'm saying the upfront evaluation costs half an hour and can prevent weeks of maintenance debt.

What I don't buy is the idea that a package's popularity is sufficient evidence to install it without further analysis. GitHub stars don't pay the cost of a migration when the library goes unsupported.

What I do buy: implementing your own logic when the dependency alternative drags in 30 transitives, has no types, or has a maintainer who hasn't responded in a year. In those cases, 80 well-tested lines of your own code are a more honest investment than delegating to a package you can't control.

The next concrete step: open the package.json of the most active project you're currently working on. Pick the five dependencies you know the least about. Run pnpm why <package> on each one and look at the repository on GitHub. In at least one of them, you'll find something that deserves a conversation about whether it's still worth keeping.

Original sources:

npm package documentation: https://docs.npmjs.com/about-packages-and-modules
npm blog — event-stream incident (2018): https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident

This article was originally published on juanchi.dev

Dependencias npm: cómo evaluar una librería antes de meterla en producción

Juan Torchia — Mon, 22 Jun 2026 12:02:37 +0000

Dependencias npm: cómo evaluar una librería antes de meterla en producción

En 2005, cuando administraba redes en un cyber café a los 16, aprendí algo que no estaba en ningún manual: cada cable que conectabas era deuda. Si el proveedor de ese cable desaparecía o cambiaba el conector, el problema era tuyo. No del proveedor, no del cliente. Tuyo. Hoy, cuando miro un package.json con 180 dependencias directas en un proyecto TypeScript, pienso exactamente lo mismo. Cada entrada en ese archivo es un cable que alguien va a tener que mantener. Y en la mayoría de los casos, ese alguien sos vos.

Mi tesis es directa: agregar una dependencia npm no es solo instalar código — es asumir su mantenimiento, su historial de CVEs, sus dependencias transitivas y el costo de salida cuando la librería quede abandonada. La pregunta no es "¿funciona?". La pregunta es "¿qué pasa cuando deje de funcionar en seis meses?".

Por qué evaluar dependencias npm es una decisión de mantenimiento, no solo de seguridad

La documentación oficial de npm define un paquete como "un archivo o directorio descrito por un package.json" (npm docs). Eso es todo lo que garantiza npm como plataforma: que el archivo existe y tiene metadatos. Nada sobre si el autor sigue activo, si tiene tests, si los tipos son correctos o si vas a poder actualizar en dos años sin romper la mitad del sistema.

Lo que la doc oficial no dice — y donde la gente se quema — es que un paquete publicado puede quedarse congelado en el tiempo. El autor puede no tener tiempo, puede abandonar el proyecto o puede simplemente no enterarse de un CVE relevante. Y en ese momento, la deuda es tuya.

Hay tres dimensiones que importan antes de instalar algo en un proyecto TypeScript con pnpm:

Mantenimiento activo: ¿Cuándo fue el último commit? ¿Hay PRs abiertas sin respuesta hace meses? ¿Tiene releases en el último año?
Superficie de ataque y tipos: ¿El paquete tiene tipos propios (@types/) o los genera? ¿Cuántas dependencias transitivas arrastra?
Costo de salida: Si mañana necesitás sacarlo, ¿cuánto código propio cambiás?

Cómo auditar una dependencia antes de `pnpm add`

La receta habitual es: buscar en npm, ver si tiene estrellas en GitHub, instalarlo y listo. El problema es que eso mide popularidad, no calidad ni longevidad. Popularidad y mantenimiento activo no son lo mismo.

Acá está el proceso que uso, paso a paso y reproducible:

1. Revisar el estado real del repositorio

Antes de instalar, abrí el repo en GitHub y mirá:

Último commit en main: si tiene más de 12 meses sin actividad y no es una librería de utilidad estable (tipo lodash), es una señal.
Issues abiertas: ¿Hay bugs sin respuesta desde hace meses? ¿CVEs mencionados y no parchados?
CHANGELOG o releases: un proyecto serio tiene historial de versiones. Si no lo tiene, la superficie de riesgo sube.

2. Analizar las dependencias transitivas con `pnpm why`

# Instalá en un proyecto de prueba aislado
pnpm add <nombre-del-paquete>

# Mirá qué trajo consigo
pnpm why <nombre-del-paquete>

# O un árbol completo de dependencias
pnpm list --depth=3

Una dependencia que parece chica puede arrastrar 40 paquetes transitivos. Eso no es automáticamente malo, pero si dos de esos 40 tienen CVEs activos, el problema es tuyo aunque el código propio no los llame directamente.

3. Correr una auditoría de seguridad desde el inicio

# Auditoría básica con npm (funciona también en proyectos pnpm)
npm audit

# Para ver solo vulnerabilidades críticas y altas
npm audit --audit-level=high

# Si querés el JSON para procesarlo
npm audit --json | jq '.vulnerabilities | to_entries[] | select(.value.severity == "critical")'

npm audit usa la base de datos del npm Advisory Database para cruzar versiones instaladas contra CVEs conocidos. No es infalible — hay vulnerabilidades que aún no tienen advisory — pero es el piso mínimo razonable antes de comprometerse con una dependencia.

4. Verificar los tipos TypeScript

En un proyecto TypeScript, una dependencia sin tipos es fricción garantizada. Revisá:

# ¿El paquete tiene tipos propios?
cat node_modules/<paquete>/package.json | grep '"types"'

# ¿Hay @types/ disponibles?
npm info @types/<paquete>

Si el paquete no tiene tipos propios y los @types/ son mantenidos por la comunidad (no por el autor original), tenés dos fuentes distintas de desfasaje. Cuando el paquete actualiza y @types/ no, el compilador falla de formas que no son obvias.

5. Evaluar el costo de salida con una interfaz propia

Este es el paso que más se saltea. La pregunta no es solo "¿funciona hoy?" sino "¿cuánto código cambio si mañana lo saco?".

// Patrón que reduce el costo de salida:
// Wrapeá la dependencia detrás de una interfaz propia

// ❌ Usar la dependencia directamente en toda la codebase
import { parse } from 'alguna-lib-de-fechas'
const fecha = parse('2025-01-15')

// ✅ Abstraer detrás de un módulo propio
// lib/fechas.ts
import { parse as _parse } from 'alguna-lib-de-fechas'

export function parsearFecha(input: string): Date {
  return _parse(input) // un solo punto de entrada
}

Si la librería está en 40 archivos distintos sin abstracción, sacarla cuesta una refactorización mayor. Si está en un módulo propio, sacarla cuesta un reemplazo de implementación interno.

Los errores más comunes al evaluar dependencias npm

Error 1: Confundir descargas semanales con estabilidad

Los números de descargas en npm incluyen mirrors automáticos, CIs y pipelines. Una librería con 2M de descargas semanales puede tener un mantenedor que no mergea PRs hace un año. Las descargas son lagging indicator de popularidad pasada, no garantía de soporte futuro.

Error 2: Ignorar las `devDependencies` en proyectos con build steps

Si una devDependency vulnerada está involucrada en el build (babel, webpack, esbuild, tsx), el código que genera puede estar comprometido. El campo devDependencies en package.json separa intención, no riesgo. Si pasa por el compilador, importa.

Error 3: No mirar el `peerDependencies`

# Mirá qué versiones de React/Node espera la lib
npm info <paquete> peerDependencies

Una librería que pide React 17 como peer en un proyecto React 19 puede funcionar, o puede generar bugs silenciosos de contexto duplicado. Los peer conflicts son uno de los costos ocultos más frecuentes en actualizaciones de stack.

Error 4: Asumir que un paquete pequeño es seguro

La superficie de ataque no es proporcional al tamaño. El incidente de event-stream en 2018 mostró que un paquete de utilidad pequeño, transferido a un mantenedor nuevo, puede convertirse en vector de ataque. Que sea pequeño no lo hace inofensivo. (Fuente: npm blog sobre el incidente)

Este tipo de riesgo conecta directamente con lo que escribí sobre OAuth Scope Creep: la superficie de ataque se acumula en los bordes, no en el centro.

Matriz de decisión: ¿agrego esta dependencia o no?

Criterio	Verde (agregar)	Amarillo (evaluar más)	Rojo (evitar o wrappear)
Último release	< 6 meses	6-18 meses	> 18 meses sin actividad
Tipos TypeScript	Incluidos en el paquete	`@types/` activos y alineados	Sin tipos o `@types/` desactualizados
CVEs activos	Ninguno	Bajos sin exploit público	Críticos o altos sin parche
Deps transitivas	< 10	10-40	> 40 o con deps con CVEs
Costo de salida	Fácil de wrappear	Acoplamiento moderado	Invasivo en múltiples módulos
Mantenedor activo	Responde issues/PRs	Lento pero responde	Sin actividad visible

Si una dependencia cae en "Rojo" en más de dos criterios, la pregunta correcta es: ¿realmente necesito esta abstracción o puedo implementar la lógica específica que necesito en 50 líneas propias?

Cuando trabajo con proyectos usando pnpm workspaces — como describí en el post sobre pnpm workspaces y CI en Railway — esta evaluación importa el doble: una dependencia problemática en un paquete compartido del monorepo la heredan todos los apps del workspace.

Lo que esta checklist no puede garantizar

Siendo honesto sobre los límites:

No predice el abandono futuro: una librería con releases recientes puede quedar abandonada mañana. La checklist mide el estado actual, no el futuro.
npm audit no cubre todos los vectores: las vulnerabilidades de lógica de negocio, los supply chain attacks sofisticados y los CVEs no reportados no aparecen en la auditoría estándar. Es el piso, no el techo.
El costo de salida real solo se mide en práctica: estimar el costo de remover una dependencia es una heurística. Hasta que no lo hacés, es una proyección. Si el proyecto ya tiene la dependencia profundamente integrada, la evaluación retrospectiva es más costosa que la prospectiva.
Las métricas de GitHub son indicadores, no pruebas: un repositorio archivado puede ser estable porque llegó a feature-complete. Un repo con muchos commits puede ser inestable por refactorizaciones constantes. El contexto importa.

FAQ: Evaluar dependencias npm en proyectos TypeScript

¿Cuántas dependencias directas es "demasiado" en un proyecto TypeScript?

No hay un número universal. Lo que sí es señal de alerta es tener más de 50-60 dependencias directas sin haber evaluado activamente cuáles son reemplazables por implementaciones propias. El criterio no es el conteo sino si cada entrada en dependencies tiene una razón clara que no pueda resolverse en menos de 100 líneas de código propio.

¿pnpm tiene ventajas de seguridad sobre npm o yarn para este tipo de auditoría?

pnpm tiene un modelo de almacenamiento distinto (content-addressable store) que evita duplicación y hace más predecible el árbol de dependencias. Pero para auditorías de CVEs, npm audit sigue siendo la herramienta estándar y funciona con cualquier lockfile. La ventaja de pnpm en este contexto es más de predictibilidad del árbol que de seguridad intrínseca.

¿Qué hago si una dependencia tiene un CVE pero no hay fix disponible?

Primero, evaluá si el CVE aplica a cómo la usás. Muchos CVEs tienen condiciones de explotación específicas que pueden no aplicar en el contexto propio. Si aplica, buscá un fork con el fix, reemplazá la dependencia o implementá la funcionalidad mínima necesaria vos mismo. Quedarse con la dependencia vulnerable y "anotarlo para después" es el camino más cómodo y el más costoso a mediano plazo.

¿Tiene sentido evaluar las devDependencies con el mismo rigor?

Menos rigor, pero no cero. Las herramientas de build, linters y compiladores que pasan por el pipeline de CI merecen revisión básica. Una devDependency que solo se usa en la máquina local tiene menos urgencia que una que participa en generar el artefacto que va a producción.

¿Cómo evalúo una dependencia cuando no tiene repositorio público visible?

Si un paquete npm no tiene un repositorio público linkado y tiene más de un par de meses de existencia, el criterio por defecto es no instalarlo en un proyecto serio. La ausencia de fuente pública no implica malicia, pero elimina la posibilidad de auditoría de código. Sin source visible, el análisis se limita a lo que el paquete declara en su package.json, que es información incompleta.

¿Cómo afecta esto al mantenimiento de un monorepo con múltiples apps?

Una dependencia problemática en un paquete shared/ del monorepo se propaga a todos los consumers automáticamente. Eso hace que la evaluación previa sea más importante, no menos. El costo de un CVE o una breaking change en una dependencia compartida se multiplica por la cantidad de apps del workspace. Vale la pena dedicar más tiempo a las dependencias de los paquetes compartidos que a las específicas de una sola app.

Mi postura y el próximo paso concreto

Agregar una dependencia npm es una decisión técnica con consecuencias que se extienden mucho más allá del sprint actual. No estoy diciendo que haya que evitar librerías — eso sería absurdo en un ecosistema donde la composición es el modelo. Estoy diciendo que la evaluación previa cuesta media hora y puede evitar semanas de deuda de mantenimiento.

Lo que no compro es la idea de que la popularidad de un paquete sea suficiente evidencia para instalarlo sin más análisis. Las estrellas en GitHub no pagan el costo de una migración cuando la librería queda sin soporte.

Lo que sí compro: implementar la lógica propia cuando la alternativa de dependencia arrastra 30 transitivas, no tiene tipos o tiene un mantenedor que no responde desde hace un año. En esos casos, 80 líneas propias bien testeadas son una inversión más honesta que delegar en un paquete que no podés controlar.

El próximo paso concreto: abrí el package.json del proyecto más activo en el que estés trabajando. Elegí las cinco dependencias que menos conocés en detalle. Corré pnpm why <paquete> en cada una y mirá el repositorio en GitHub. En al menos una vas a encontrar algo que merece una conversación sobre si sigue valiendo la pena.

Fuente original:

npm package documentation: https://docs.npmjs.com/about-packages-and-modules
npm blog — event-stream incident (2018): https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident

Este artículo fue publicado originalmente en juanchi.dev

lode: Reimplementing DVC's core in Go without breaking the format

Juan Torchia — Sun, 21 Jun 2026 07:58:03 +0000

lode: Reimplementing DVC's core in Go without breaking the format

There's a type of open source project that earns my immediate respect: one that clearly defines what it doesn't do. lode is one of those.

When I first read the README, the sentence that stopped me was: "lode never invents a format; your repo stays a DVC repo." In an ecosystem where every new tool wants to be the center of gravity, that level of intentional restraint is rare. And it's exactly the technical decision I want to dissect here.

My thesis: format compatibility is not a marketing feature. It's operational risk management. In ML teams where DVC is already baked into pipelines, CI scripts, and audit flows, adopting a tool that invents its own artifact format requires a migration with a freeze window. lode eliminates that cost entirely, and it has a price: pipelines and dvc repro are out of scope. The trade-off is honest.

The problem lode attacked

DVC is the de facto standard for versioning datasets and models in ML projects. The problem isn't conceptual: it's runtime. When you have a directory with 20,000 files and run dvc add big/, DVC hashes sequentially in Python, with all the friction of an interpreter. The repo's README shows concrete measurement on the same repo:

$ time dvc add big/      # 20,000 files
real    0m5.79s

$ time lode add big/     # same repo, identical result byte for byte
real    0m0.44s

That's roughly a ~13× difference in that case. I won't universalize that number as a performance guarantee: it depends on hardware, filesystem, individual file sizes, and how many are already in the state DB. What is reproducible is the mechanism: Go compiles to native binary without VM overhead, hashing runs with NumCPU goroutines in parallel, and the state DB (bbolt, under internal/hashfile) stores (inode, mtime, size) → md5 to skip files that haven't changed. That combination makes technical sense independent of the exact number.

The friction of the hot path matters more than it seems in ML workflows. A slow dvc status makes data scientists avoid it, leading to commits without updated pointer files, leading to broken reproducibility. Accelerating the happy path has real impact on team discipline.

The invariant that's non-negotiable

What interested me most about the repo was reading docs/ARCHITECTURE.md and finding this written as a cardinal principle:

Byte-compatibility with DVC. Anything that changes a serialized artifact (.dvc, .dir, cache/remote layout) must keep the oracle test (tests/oracle/, which runs the real dvc and compares bytes) green.

This isn't a throwaway comment in the README. It's a design invariant that runs through the entire architecture. The internal/dvcfile package reads and writes .dvc files byte-exact with DVC 3.x. The internal/hashfile package reimplements .dir manifest serialization to match exactly with Python's json.dumps (which has a specific key order). The internal/lock package implements DVC-compatible locking so both tools can coexist in the same repo without corruption.

The architecture is organized so format risk is concentrated in specific places:

internal/
├── dvcfile/   # Read/write .dvc — byte-exact compatibility with DVC 3.x
├── hashfile/  # Parallel MD5 + .dir serialization (the trickiest compat detail)
├── cache/     # Content-addressed object store: files/md5/<2>/<rest>
├── remote/    # S3-compatible backend via minio-go
├── transfer/  # Push/fetch with integrity verification
├── checkout/  # Materialization: reflink → hardlink/symlink → copy
└── lock/      # DVC-compatible locking (global flock + JSON rwlock)

Each package has a single responsibility and the highest-risk format code lives in internal/dvcfile and internal/hashfile/tree.go. That makes it easier to reason about where compatibility can break if DVC changes its format in a future version.

CI has an oracle job that installs real DVC (via pipx install \"dvc[s3]\") and runs go test ./tests/oracle/... to compare bytes. If the invariant breaks, the pipeline fails. No ambiguity.

The honest trade-off: what you accelerate and what stays out

lode implements the data layer: add, status, push, pull, fetch, checkout, gc, remote, doctor, verify. That covers the daily hot path for a team versioning datasets.

What's not in scope: dvc repro, dvc run, pipelines, transformation DAGs. The architecture didn't pretend that was straightforward to reimplement with byte-identical compatibility. They chose to define a clear perimeter and execute it well, instead of building a partial clone of all of DVC.

Look at the README: "For ML pipelines (dvc repro), keep using DVC — lode accelerates the data layer and coexists with it." That sentence isn't an apology. It's a design decision. The two tools coexist because they share the same lock (internal/lock uses global flock + JSON rwlock compatible with DVC) and the same artifact format. You can run lode add and then dvc repro without any additional synchronization layer.

The main risk I see with any format reimplementation is drift: if DVC 4.x changes the .dvc file schema or the .dir JSON key order, lode has to update in parallel or compatibility silently breaks. The oracle test mitigates this, but only for the version of DVC installed in CI. That's not a flaw in lode's design; it's the structural cost of being compatible with a format you don't control. A team adopting it should plan for that maintenance.

The state DB: optimization with graceful degradation

The mechanism I liked most about the design is how they think about the state DB. The architecture spells it out explicitly:

The state DB (inode, mtime, size) -> md5 is an optimization, never a source of truth. It can produce a false "up to date" only if a file's content changes while all three keys stay identical (e.g. NFS quirks, restored backups that reset mtimes, recycled inodes). For those cases --rehash (and a corrupt/unreadable state DB) degrade to a full re-hash — the always-correct path.

That's a clear contract about the optimization's limits. Corrupt state or an NFS edge case doesn't break correctness: it degrades to the slow but always-correct path. The --rehash flag exists exactly for this. On network filesystems or CI environments where inodes can be recycled, it's something to keep in mind.

What looks like good technical maturity to me is that this limit is documented in the architecture, not buried in a GitHub issue. A team adopting it knows exactly when lode status can lie (and how to force the correct path).

The static binary as an operational argument

CGO_ENABLED=0 in the build means a binary with no dynamic dependencies. That has practical implications in MLOps:

make build       # single binary with no CGO, no external runtime
make test-short  # unit + oracle, no external services
make test        # full suite — needs MinIO and real dvc

In a training Docker image, installing Python + DVC + S3 dependencies adds layers that can total hundreds of MB and minutes of build time. A static binary is COPY lode /usr/local/bin/lode and done. The release pipeline uses goreleaser with SBOM (via syft), keyless signing with cosign (OIDC), and build provenance attestation (SLSA). For a freshly built project, that level of rigor in the supply chain is a positive signal about how they think about long-term maintenance.

My position

I don't buy the claim of "drop-in compatible" in absolute terms: lode is drop-in compatible for the data layer. If your team's workflow depends on dvc repro, part of your flow stays in DVC. That's not a problem, but you have to name it honestly to avoid mismatched expectations.

What I do accept without reservation: the coexistence approach is technically correct. The alternative of inventing a custom format would shift the performance cost to a migration and lock-in cost. In ML teams where data artifacts are also audit evidence (experiment reproducibility, model traceability), changing that artifact format has a cost beyond engineering time.

The trade-off that feels honest to me: lode solves the hot-path performance problem with a constraint that in most cases is tolerable. The risk is format drift when DVC updates its spec. The oracle test in CI is the detection mechanism, but it requires active maintenance discipline.

If you manage DVC repos with large datasets and dvc add or dvc push time is a real bottleneck, lode deserves an evaluation. The fact that lode verify and dvc status can run on the same artifacts and give the same result is the contract that makes the evaluation reversible at no cost.

What would you do if DVC's format changes in a minor version and silently breaks compatibility in production? Do you have an oracle test to catch it, or do you discover it on the next dvc repro?

Repo analyzed: getlode/lode @ commit b6e6d34

This article was originally published on juanchi.dev

lode: Reimplementando el core de DVC en Go sin romper el formato

Juan Torchia — Sun, 21 Jun 2026 07:57:57 +0000

lode: Reimplementando el core de DVC en Go sin romper el formato

Hay un tipo de proyecto open source que me genera respeto inmediato: el que define con claridad lo que no hace. lode es uno de esos.

Cuando leí el README por primera vez, la frase que me frenó fue esta: "lode never invents a format; your repo stays a DVC repo." En un ecosistema donde cada herramienta nueva quiere ser el centro de gravedad, ese nivel de renuncia intencional es raro. Y es exactamente la decisión técnica que quiero diseccionar acá.

Mi tesis: la compatibilidad de formato no es una feature de marketing. Es una gestión de riesgo operativo. En equipos de ML donde DVC ya está integrado en pipelines, scripts de CI y flujos de auditoría, adoptar una herramienta que inventa su propio formato de artefactos exige una migración con ventana de congelamiento. lode evita ese costo completamente, y eso tiene un precio: pipelines y dvc repro quedan fuera de scope. El trade-off es honesto.

El problema que lode atacó

DVC es el estándar de facto para versionar datasets y modelos en proyectos de ML. El problema no es conceptual: es el runtime. Cuando tenés un directorio con 20.000 archivos y corrés dvc add big/, DVC hashea secuencialmente en Python, con toda la fricción del intérprete. El README del repo muestra una medición concreta sobre el mismo repo:

$ time dvc add big/      # 20,000 archivos
real    0m5.79s

$ time lode add big/     # mismo repo, resultado idéntico byte por byte
real    0m0.44s

Eso es una diferencia de ~13× en ese caso. No voy a universalizar ese número como garantía de performance general: depende del hardware, el sistema de archivos, el tamaño de los archivos individuales y cuántos ya están en el state DB. Lo que sí es reproducible es el mecanismo: Go compila a binario nativo sin overhead de VM, el hashing corre con NumCPU goroutines en paralelo, y el state DB (bbolt, bajo internal/hashfile) guarda (inode, mtime, size) → md5 para saltear archivos que no cambiaron. Esa combinación tiene sentido técnico independientemente del número exacto.

La fricción del hot path importa más de lo que parece en flujos de ML. Un dvc status lento hace que los data scientists lo eviten, lo que lleva a commits sin pointer files actualizados, lo que lleva a reproductibilidad rota. Acelerar el camino feliz tiene impacto real en disciplina del equipo.

La invariante que no se negocia

Lo que más me interesó del repo fue leer docs/ARCHITECTURE.md y encontrar esto escrito como principio cardinal:

Byte-compatibility with DVC. Anything that changes a serialized artifact (.dvc, .dir, cache/remote layout) must keep the oracle test (tests/oracle/, which runs the real dvc and compares bytes) green.

No es un comentario en el README. Es una invariante de diseño que atraviesa toda la arquitectura. El paquete internal/dvcfile lee y escribe archivos .dvc byte-exact con DVC 3.x. El paquete internal/hashfile reimplementa la serialización del .dir manifest para que matchee exactamente con json.dumps de Python (que tiene un orden de claves específico). El paquete internal/lock implementa locking compatible con DVC para que ambas herramientas puedan coexistir en el mismo repo sin corromperse.

La arquitectura está organizada para que el riesgo de formato esté concentrado en lugares específicos:

internal/
├── dvcfile/   # Lee/escribe .dvc — compatibilidad byte-exacta con DVC 3.x
├── hashfile/  # MD5 paralelo + serialización .dir (el detalle más delicado de compat)
├── cache/     # Object store content-addressed: files/md5/<2>/<rest>
├── remote/    # Backend S3-compatible via minio-go
├── transfer/  # Push/fetch con verificación de integridad
├── checkout/  # Materialización: reflink → hardlink/symlink → copy
└── lock/      # Locking DVC-compatible (flock global + rwlock JSON)

Cada paquete tiene una responsabilidad única y el código de mayor riesgo de formato está aislado en internal/dvcfile e internal/hashfile/tree.go. Eso facilita razonar sobre dónde puede romperse la compatibilidad si DVC cambia su formato en una versión futura.

El CI tiene un job oracle que instala el DVC real (via pipx install "dvc[s3]") y corre go test ./tests/oracle/... para comparar bytes. Si la invariante se rompe, el pipeline falla. No hay ambigüedad.

El trade-off honesto: qué acelerás y qué dejás afuera

lode implementa el data layer: add, status, push, pull, fetch, checkout, gc, remote, doctor, verify. Eso cubre el hot path diario de un equipo que versiona datasets.

Lo que no está en scope: dvc repro, dvc run, pipelines, DAGs de transformación. La arquitectura no fingió que eso era sencillo de reimplementar con compatibilidad byte-identical. Optaron por definir un perímetro claro y ejecutarlo bien, en lugar de hacer un clon parcial de todo DVC.

Mirá el README: "For ML pipelines (dvc repro), keep using DVC — lode accelerates the data layer and coexists with it." Esa frase no es una disculpa. Es una decisión de diseño. Los dos tools conviven porque comparten el mismo lock (internal/lock usa flock global + rwlock JSON compatible con DVC) y el mismo formato de artefactos. Podés correr lode add y después dvc repro sin ninguna capa de sincronización adicional.

El riesgo principal que veo con cualquier reimplementación de formato es la deriva: si DVC 4.x cambia el schema del .dvc file o el orden de claves del .dir JSON, lode tiene que actualizarse en paralelo o la compatibilidad se rompe silenciosamente. El oracle test mitiga esto, pero solo para la versión de DVC que está instalada en CI. Eso no es un defecto del diseño de lode; es el costo estructural de ser compatible con un formato que no controlás. Un equipo que lo adopte debería planear ese seguimiento.

El state DB: optimización con degradación grácil

El mecanismo que más me gustó del diseño es cómo piensan el state DB. La arquitectura lo dice explícitamente:

The state DB (inode, mtime, size) -> md5 is an optimization, never a source of truth. It can produce a false "up to date" only if a file's content changes while all three keys stay identical (e.g. NFS quirks, restored backups that reset mtimes, recycled inodes). For those cases --rehash (and a corrupt/unreadable state DB) degrade to a full re-hash — the always-correct path.

Eso es un contrato claro sobre los límites de la optimización. El estado corrupto o un edge case de NFS no rompen la correctness: degradan a la ruta lenta pero siempre correcta. El flag --rehash existe exactamente para eso. En sistemas de archivos de red o entornos de CI donde los inodes pueden reciclarse, es algo a tener en cuenta.

Lo que me parece un buen indicador de madurez técnica es que este límite está documentado en la arquitectura, no escondido en un issue de GitHub. Un equipo que lo adopte sabe exactamente cuándo lode status puede mentir (y cómo forzar la ruta correcta).

El binario estático como argumento operativo

CGO_ENABLED=0 en el build significa un binario sin dependencias dinámicas. Eso tiene implicaciones prácticas en MLOps:

make build       # binario único sin CGO, sin runtime externo
make test-short  # unit + oracle, sin servicios externos
make test        # suite completa — necesita MinIO y dvc real

En una imagen Docker de entrenamiento, instalar Python + DVC + dependencias S3 agrega capas que pueden sumar cientos de MB y minutos de build. Un binario estático es COPY lode /usr/local/bin/lode y terminó. El release pipeline usa goreleaser con SBOM (via syft), firma keyless con cosign (OIDC) y attestation de build provenance (SLSA). Para un proyecto recién armado, ese nivel de rigor en la cadena de supply chain es una señal positiva sobre cómo piensan el mantenimiento a largo plazo.

Mi postura

No compro el claim de "drop-in compatible" de forma absoluta: lode es drop-in compatible para el data layer. Si el workflow del equipo depende de dvc repro, hay una parte del flujo que sigue en DVC. Eso no es un problema, pero hay que nombrarlo honestamente para no generar expectativas incorrectas.

Lo que sí acepto sin reservas: el enfoque de coexistencia es técnicamente correcto. La alternativa de inventar un formato propio trasladaría el costo de la performance a un costo de migración y lock-in. En equipos de ML donde los artefactos de datos son también evidencia de auditoría (reproducibilidad de experimentos, trazabilidad de modelos), cambiar el formato de esos artefactos tiene un costo que va más allá del tiempo de ingeniería.

El trade-off que me parece honesto: lode resuelve el problema de performance del hot path con una restricción que en la mayoría de los casos es tolerable. El riesgo es la deriva de formato cuando DVC actualice su spec. El oracle test en CI es el mecanismo de detección, pero requiere disciplina de mantenimiento activo.

Si manejás repos DVC con datasets grandes y el tiempo de dvc add o dvc push es un cuello de botella real, lode merece una evaluación. El hecho de que lode verify y dvc status puedan correr sobre los mismos artefactos y dar el mismo resultado es el contrato que hace que la evaluación sea reversible sin costo.

¿Qué harías vos si el formato de DVC cambia en una minor version y rompe silenciosamente la compatibilidad en producción? ¿Tenés un oracle test que lo detecte, o lo descubrís en el próximo dvc repro?

Repo analizado: getlode/lode @ commit b6e6d34

Este artículo fue publicado originalmente en juanchi.dev

OWASP LLM Top 10 in Production: How I Audited My TypeScript Agent Pipeline Against All 10 Risks — and What I Found

Juan Torchia — Sat, 20 Jun 2026 12:02:58 +0000

OWASP LLM Top 10 in Production: How I Audited My TypeScript Agent Pipeline Against All 10 Risks — and What I Found

I was reviewing a system prompt for an MCP agent I'd written three weeks earlier when something hit me hard: the prompt was accepting instructions from the output of an external tool. No sanitization. No validation. No limits whatsoever on what it could do with that output. The tool called a public API, got back JSON, and that JSON landed directly in the model's context.

That's when I opened the OWASP LLM Top 10 and stopped reading it like a list of best practices — and started using it for what it actually is: an audit framework.

My thesis is simple: most posts about the OWASP LLM Top 10 explain the ten risks to you. None of them show you how to run them against your own stack and what you actually find when you do it seriously. That's the difference between "reading the checklist" and "auditing the pipeline." This post is the second thing.

The Stack I Audited — and Why Context Matters

Before getting into the checklist, some context: I have a TypeScript agent pipeline with three layers that interact with each other:

Structured system prompts — instructions that define agent behavior, kept separate from user context
MCP tools — tools registered following the Model Context Protocol, which the agent can call during a session
Cline as the client — orchestrating execution inside the editor, with access to filesystem, terminal, and other tools

Each layer has a different attack surface. That's exactly what the OWASP LLM Top 10 let me see with surgical precision.

All 10 Risks: What I Found in Each One

LLM01 — Prompt Injection

This was the biggest finding. My MCP agent was receiving output from external tools and injecting it directly into context with zero sanitization layer. In an adversarial scenario, any API the agent queried could return text specifically crafted to overwrite the system prompt instructions.

The broken pattern looked like this:

// ❌ Insecure pattern: external output goes straight into context
async function fetchContextAndInject(url: string): Promise<string> {
  const response = await fetch(url);
  const data = await response.json();
  // data.content reaches the model context with no filtering whatsoever
  return data.content;
}

What I changed it to:

// ✅ Structural validation before injecting into context
import { z } from "zod";

const ExternalResponseSchema = z.object({
  // Only accept fields with defined types — free-form strings flagged as suspicious
  title: z.string().max(200),
  summary: z.string().max(1000),
  // Anything not in the schema gets discarded
});

async function fetchContextSafe(url: string): Promise<string> {
  const response = await fetch(url);
  const raw = await response.json();
  // If the schema fails, the agent gets a structured error — not the raw payload
  const parsed = ExternalResponseSchema.parse(raw);
  return `Title: ${parsed.title}\nSummary: ${parsed.summary}`;
}

I used Zod — which was already in the stack for API validation — as the first line of defense. It's not a complete solution to prompt injection, but it reduces the structural attack surface.

LLM02 — Insecure Output Handling

The second problem: agent output was reaching the UI without escaping. In an agent that generates HTML or Markdown, that's potential XSS if the output gets rendered directly.

I traced every place where model output touched the DOM and added explicit sanitization before any render. If the agent generates code, that code goes into a <pre> block with escaped characters — not into an innerHTML.

LLM03 — Training Data Poisoning

Here the OWASP LLM Top 10 points to risks in the base model, not the application. In my case the model is Claude via API — I don't control the fine-tuning or the dataset. My only action was to document this dependency explicitly: if Anthropic has a problem here, I have a problem here. No system prompt compensates for that.

Honest limit: you can't audit this from the application layer. It's a dependency you take as a trust boundary.

LLM04 — Model Denial of Service

I checked whether I had rate limiting on the endpoints that trigger model calls. I didn't — at least not in the local testing context. In a production scenario this is critical: a badly designed loop or a tool that calls recursively can fire dozens of model requests in seconds.

I added a simple iteration cap to the agent loop:

// Iteration control to prevent infinite loops in the agent
const MAX_ITERATIONS = 10;
let iterations = 0;

while (agentShouldContinue && iterations < MAX_ITERATIONS) {
  iterations++;
  const result = await runAgentStep();
  agentShouldContinue = result.continueLoop;
}

if (iterations >= MAX_ITERATIONS) {
  // Explicit log — I want to know if this ever fires
  console.warn("[agent] Iteration limit reached — review loop");
}

LLM05 — Supply Chain Vulnerabilities

This risk made me look at two things: the npm packages I use to interact with the model API, and the dependencies of my MCP tools. With pnpm workspaces (something I covered in the monorepo with Railway post) you get lockfile visibility — but that's not the same as auditing.

What I added: pnpm audit as an explicit CI step before deploying any agent. It doesn't eliminate the risk, but it makes it visible.

LLM06 — Sensitive Information Disclosure

This is where the second uncomfortable finding showed up: my system prompts contained configuration context that included names of internal tools, data structure details, and some system defaults. That context reaches the model — and if the model echoes it in its output, it's exposed.

The rule I applied: nothing you wouldn't want to see in a public log should be in a system prompt without explicit confidentiality marking. And even that isn't a guarantee — it's mitigation.

// Separate technical config from agent instructions
const SYSTEM_PROMPT_PUBLIC = `
You are a development assistant. You can use available tools
to answer technical questions.
`;

// This does NOT go into the system prompt — it lives in a separate config layer
const AGENT_CONFIG_PRIVATE = {
  toolEndpoints: process.env.TOOL_ENDPOINTS,
  internalSchema: process.env.INTERNAL_SCHEMA,
};

LLM07 — Plugin Design Flaws

My MCP tools are essentially plugins. The risk here is that a tool has broader permissions than it actually needs. I reviewed each tool and applied least privilege: a tool that reads files doesn't need write access; a tool that queries an API doesn't need filesystem access.

This connects directly to what I wrote about OAuth scope creep — the same audit pattern applies to an agent's tools.

LLM08 — Excessive Agency

This is the risk that concerns me most specifically with Cline. The agent has terminal access, can execute commands, can modify files. If the reasoning loop fails, it can cause real damage.

What I implemented: "confirm before execute" mode for any tool with an irreversible side effect. It's not automatable — it requires deliberate human friction. And that friction is the entire point.

// Explicit tool classification by impact
type ToolImpact = "read-only" | "reversible" | "destructive";

const TOOL_IMPACT_MAP: Record<string, ToolImpact> = {
  readFile: "read-only",
  listDirectory: "read-only",
  writeFile: "reversible",
  deleteFile: "destructive",
  runCommand: "destructive",
};

async function executeTool(toolName: string, args: unknown) {
  const impact = TOOL_IMPACT_MAP[toolName] ?? "destructive"; // safe fallback
  if (impact === "destructive") {
    // Pause and wait for human confirmation before executing
    await requireHumanApproval(toolName, args);
  }
  return runTool(toolName, args);
}

LLM09 — Overreliance

This isn't a purely technical risk — it's organizational. The problem is trusting the agent's output without external validation. In my pipeline, any output going to production passes through a structural validation layer before it's used as input to another system. The model can be fine, the pipeline can be fine, and the output can still be wrong.

This risk doesn't close with code. It closes with process and human review at critical nodes.

LLM10 — Model Theft

In my TypeScript agent context, this mainly applies to protecting system prompts. A well-crafted system prompt represents real work — and if it leaks, it can be replicated or used to bypass restrictions.

What I implemented: system prompts don't live in frontend code. They're served from an authenticated endpoint, they're not logged in plain text, and they don't get exposed in the client bundle.

What the OWASP LLM Top 10 Doesn't Tell You (Which Matters Just as Much)

Here's what the list doesn't resolve on its own:

It doesn't tell you the priority order for your stack. LLM01 (prompt injection) was critical in my case; LLM03 (training data poisoning) is irrelevant from the application layer. Without applying it against your concrete architecture, you don't know which one is urgent.

It gives you no criteria for the trust boundary of the base model. If you use Claude, GPT-4, or any external API, LLM03 and part of LLM05 are dependencies you take as given. The framework names them, but the mitigation is out of your hands.

It doesn't distinguish between runtime risks and design risks. LLM01 and LLM02 are problems you can detect and mitigate at runtime. LLM08 (excessive agency) is a design problem — if the agent has too many permissions, a runtime patch doesn't fix it.

I have a post on OpenTelemetry in Next.js where I talk about traces that survive the edge. That kind of observability helps here too: if you can't see which tools the agent called and with what args, you can't audit LLM08 in production.

Applied Checklist: The Real State of Each Risk in My Pipeline

Risk	State Found	Action Taken
LLM01 Prompt Injection	❌ Vulnerable	Zod schema on external tool output
LLM02 Insecure Output	⚠️ Partial	Explicit escaping before render
LLM03 Training Data	🔵 Out of scope	Documented as trust boundary
LLM04 Model DoS	⚠️ No limit	Added max iterations + log
LLM05 Supply Chain	⚠️ Invisible	`pnpm audit` in CI
LLM06 Info Disclosure	❌ Leaky prompts	Separated config from system prompt
LLM07 Plugin Flaws	⚠️ Partial	Permission review per tool
LLM08 Excessive Agency	⚠️ No friction	Confirm before execute on destructive tools
LLM09 Overreliance	🔵 Process	Human validation at critical nodes
LLM10 Model Theft	⚠️ Prompts exposed	Prompts moved to authenticated endpoint

❌ = critical finding | ⚠️ = partial mitigation | 🔵 = outside application control

FAQ

Does the OWASP LLM Top 10 apply to agents built on Claude or GPT-4 via API?

Yes, with nuance. LLM01, LLM02, LLM06, LLM07, LLM08, and LLM10 are application-layer risks — they apply regardless of which model you use. LLM03 (training data) and part of LLM05 are provider risks: if you use an external API, you take them as a trust boundary. The audit starts with the risks you can actually control.

Is Zod enough to mitigate prompt injection?

No. Zod validates the structure of external output before it reaches context — that reduces the surface area, but it doesn't eliminate the risk. A well-formed adversarial payload can pass schema validation. Zod is one layer, not a complete solution. Real mitigation combines schema validation, system prompt constraints, and human review at critical points.

Is Cline safe to use in production as an agent orchestrator?

Cline has access to the filesystem, terminal, and other tools with real effects. That's not inherently unsafe — it's the functionality that makes it useful. The risk (LLM08) is in the design: if the agent can execute destructive commands without human confirmation, the risk is real regardless of how well Cline is configured. My rule: any tool with an irreversible effect requires explicit approval.

How often should you run this audit?

Every time you change the agent's architecture: you add a new tool, change the system prompt, or modify how the agent consumes external outputs. It's not a one-time audit — it's a checklist that runs against every structural change. If you add observability (OpenTelemetry is one option), you can catch runtime anomalies between audits.

Does the OWASP LLM Top 10 cover multi-agent risks or just single-agent?

The current version (2025) primarily covers per-agent risk. In multi-agent architectures, LLM01's surface multiplies: each agent can become an injection vector for the others. The framework names the risk, but the mitigation detail for multi-agent pipelines is left to each team.

Which risk should I tackle first if I have limited time?

LLM01 (prompt injection) if your agent consumes external output — it's the most exploitable and the most overlooked. LLM08 (excessive agency) if the agent has access to tools with irreversible effects — it's the one that can do the most damage when something goes wrong. The rest depend on your specific stack, but these two are the absolute floor.

The Difference Between Reading and Auditing

My position is clear: the OWASP LLM Top 10 is not something you read and consider covered. It's something you bring into a review session with the architecture diagram open in front of you, and you ask — for each risk — exactly where in the pipeline that could fail.

What I don't buy is the idea that "following best practices" is enough. Practices are abstract; the pipeline is concrete. In my case, LLM01 and LLM06 were real problems I wouldn't have found without doing the systematic audit exercise. I would have discovered them when someone motivated enough decided to exploit them.

If you already have TypeScript agents with MCP tools or elaborate system prompts, do the exercise: open the OWASP LLM Top 10, open the architecture diagram, and ask risk by risk. The result will be more interesting than the list itself.

Concrete next step: take the checklist from this table, replace the states with your own, and document the findings. An audit that isn't documented doesn't exist.

Original source:

OWASP LLM AI Security & Governance Checklist: https://owasp.org/www-project-top-10-for-large-language-model-applications/

This article was originally published on juanchi.dev

OWASP LLM Top 10 en producción: cómo audité mi pipeline de agentes TypeScript contra los 10 riesgos y qué encontré

Juan Torchia — Sat, 20 Jun 2026 12:02:53 +0000

OWASP LLM Top 10 en producción: cómo audité mi pipeline de agentes TypeScript contra los 10 riesgos y qué encontré

Estaba revisando un system prompt de un agente MCP que había escrito tres semanas antes cuando me di cuenta de algo perturbador: el prompt aceptaba instrucciones de la respuesta de una tool externa. Sin sanitización. Sin validación. Sin ningún límite sobre qué podía hacer con esa salida. La tool llamaba a una API pública, recibía JSON, y ese JSON llegaba directo al contexto del modelo.

Ahí fue cuando abrí el OWASP LLM Top 10 y paré de leerlo como lista de buenas prácticas para empezar a usarlo como lo que en realidad es: un framework de auditoría.

Mi tesis es esta: la mayoría de los posts sobre OWASP LLM Top 10 te explican los diez riesgos. Ninguno te muestra cómo correrlos contra tu stack propio y qué encontrás cuando lo hacés en serio. Esa es la diferencia entre "leer el checklist" y "auditar el pipeline". Acá está lo segundo.

El stack que audité y por qué importa el contexto

Antes de entrar al checklist, el contexto: tengo un pipeline de agentes en TypeScript con tres capas que interactúan:

System prompts estructurados — instrucciones que definen el comportamiento del agente, separadas del contexto de usuario
MCP tools — tools registradas siguiendo el Model Context Protocol, que el agente puede llamar durante una sesión
Cline como cliente — que orquesta la ejecución en el editor y tiene acceso a filesystem, terminal y otras herramientas

Cada capa tiene una superficie de ataque diferente. Eso es lo que el OWASP LLM Top 10 me permitió ver con precisión quirúrgica.

Los 10 riesgos: qué encontré en cada uno

LLM01 — Prompt Injection

Este fue el hallazgo más gordo. Mi agente MCP recibía output de tools externas y lo incorporaba al contexto sin ninguna capa de sanitización. En un escenario adversarial, cualquier API que el agente consultara podría devolver texto diseñado para sobrescribir las instrucciones del system prompt.

El patrón roto era este:

// ❌ Patrón inseguro: output externo directo al contexto
async function fetchContextAndInject(url: string): Promise<string> {
  const response = await fetch(url);
  const data = await response.json();
  // data.content llega sin ningún filtro al contexto del modelo
  return data.content;
}

Lo que cambié:

// ✅ Validación de estructura antes de incorporar al contexto
import { z } from "zod";

const ExternalResponseSchema = z.object({
  // Solo acepto campos con tipo definido — string libre marcado como sospechoso
  title: z.string().max(200),
  summary: z.string().max(1000),
  // Descarto cualquier campo que no esté en el schema
});

async function fetchContextSafe(url: string): Promise<string> {
  const response = await fetch(url);
  const raw = await response.json();
  // Si el schema falla, el agente recibe un error estructurado, no el payload crudo
  const parsed = ExternalResponseSchema.parse(raw);
  return `Título: ${parsed.title}\nResumen: ${parsed.summary}`;
}

Usé Zod — que ya tenía en el stack para validación de API — como primera línea. No es una solución completa al prompt injection, pero reduce la superficie de ataque estructural.

LLM02 — Insecure Output Handling

El segundo problema: el output del agente llegaba a la UI sin escaping. En un agente que genera HTML o Markdown, eso es XSS potencial si el output se renderiza directamente.

Revisé dónde el output del modelo llegaba al DOM y agregué sanitización explícita antes de cualquier render. Si el agente genera código, ese código va a un bloque <pre> con escape de caracteres; no a un innerHTML.

LLM03 — Training Data Poisoning

Acá el OWASP LLM Top 10 apunta a riesgos del modelo base, no de la aplicación. En mi caso el modelo es Claude vía API — no controlo el fine-tuning ni el dataset. Mi única acción fue documentar esta dependencia explícitamente: si Anthropic tiene un problema acá, yo tengo un problema acá. Ningún sistema prompt lo compensa.

Límite honesto: no podés auditar esto desde la aplicación. Es una dependencia que tomás como trust boundary.

LLM04 — Model Denial of Service

Revisé si tenía rate limiting en los endpoints que disparan llamadas al modelo. No lo tenía en el contexto de pruebas locales. En un escenario de producción esto es crítico: un loop mal diseñado o una tool que llama recursivamente puede generar decenas de requests al modelo en segundos.

Agregué un límite simple de iteraciones al loop del agente:

// Control de iteraciones para evitar loops infinitos en el agente
const MAX_ITERATIONS = 10;
let iterations = 0;

while (agentShouldContinue && iterations < MAX_ITERATIONS) {
  iterations++;
  const result = await runAgentStep();
  agentShouldContinue = result.continueLoop;
}

if (iterations >= MAX_ITERATIONS) {
  // Log explícito — quiero saber si esto se dispara
  console.warn("[agente] Límite de iteraciones alcanzado — revisar loop");
}

LLM05 — Supply Chain Vulnerabilities

Este riesgo me hizo revisar dos cosas: los paquetes npm que uso para interactuar con la API del modelo y las dependencias de mis MCP tools. Con pnpm workspaces (tema que ya cubrí en el post de monorepo con Railway) tenés visibilidad del lockfile, pero eso no es auditoría.

Lo que agregué: pnpm audit como paso explícito en CI antes del deploy de cualquier agente. No elimina el riesgo, pero lo hace visible.

LLM06 — Sensitive Information Disclosure

Acá encontré el segundo hallazgo incómodo: en los system prompts tenía contexto de configuración que incluía nombres de tools internas, estructura de datos y algunos defaults del sistema. Ese contexto llega al modelo — y si el modelo lo repite en su output, lo expone.

La regla que apliqué: nada que no quieras ver en un log público debería estar en un system prompt sin marcado explícito de confidencialidad. Y eso tampoco es garantía — es mitigación.

// Separar configuración técnica de instrucciones del agente
const SYSTEM_PROMPT_PUBLIC = `
Sos un asistente de desarrollo. Podés usar las herramientas disponibles
para responder preguntas técnicas.
`;

// Esto NO va al system prompt — va a una capa de configuración separada
const AGENT_CONFIG_PRIVATE = {
  toolEndpoints: process.env.TOOL_ENDPOINTS,
  internalSchema: process.env.INTERNAL_SCHEMA,
};

LLM07 — Plugin Design Flaws

Mis MCP tools son básicamente plugins. El riesgo acá es que una tool tenga permisos más amplios de lo necesario. Revisé cada tool y apliqué el principio de mínimo privilegio: una tool que lee archivos no necesita escribir; una tool que consulta una API no necesita acceso al filesystem.

Esto conecta con lo que escribí sobre OAuth scope creep — el mismo patrón de auditoría aplica a las tools de un agente.

LLM08 — Excessive Agency

Este es el riesgo que más me preocupa en Cline específicamente. El agente tiene acceso a terminal, puede ejecutar comandos, puede modificar archivos. Si el loop de razonamiento falla, puede hacer daño real.

Lo que implementé: modo "confirm before execute" para cualquier tool con efecto secundario irreversible. No es automatizable — requiere fricción humana deliberada. Y esa fricción es el punto.

// Clasificación explícita de tools por impacto
type ToolImpact = "read-only" | "reversible" | "destructive";

const TOOL_IMPACT_MAP: Record<string, ToolImpact> = {
  readFile: "read-only",
  listDirectory: "read-only",
  writeFile: "reversible",
  deleteFile: "destructive",
  runCommand: "destructive",
};

async function executeTool(toolName: string, args: unknown) {
  const impact = TOOL_IMPACT_MAP[toolName] ?? "destructive"; // fallback seguro
  if (impact === "destructive") {
    // Pausa y espera confirmación humana antes de ejecutar
    await requireHumanApproval(toolName, args);
  }
  return runTool(toolName, args);
}

LLM09 — Overreliance

No es un riesgo técnico puro — es organizacional. El problema es confiar en el output del agente sin validación externa. En mi pipeline, cualquier output que va a producción pasa por una capa de validación estructural antes de ser usado como input de otro sistema. El modelo puede estar seguro, el pipeline puede estar seguro, y el output puede seguir siendo incorrecto.

Este riesgo no se cierra con código. Se cierra con proceso y revisión humana en los nodos críticos.

LLM10 — Model Theft

En mi contexto de agente TypeScript, esto aplica principalmente a la protección de los system prompts. Un system prompt elaborado representa trabajo real — y si se expone, puede ser replicado o usado para evadir restricciones.

Lo que implementé: los system prompts no viven en el código del frontend. Se sirven desde un endpoint autenticado, no se loguean en texto plano y no se exponen en el bundle del cliente.

Lo que el OWASP LLM Top 10 no te dice (y es igual de importante)

Acá está lo que la lista no resuelve sola:

No te dice el orden de prioridad para tu stack. LLM01 (prompt injection) fue crítico en mi caso; LLM03 (training data poisoning) es irrelevante desde la aplicación. Sin aplicarlo contra tu arquitectura concreta, no sabés cuál es urgente.

No te da criterio para el trust boundary del modelo base. Si usás Claude, GPT-4 o cualquier API externa, LLM03 y parte de LLM05 son dependencias que tomás como dadas. El framework las nombra, pero la mitigación no está en tus manos.

No distingue entre riesgos de runtime y riesgos de diseño. LLM01 y LLM02 son problemas que podés detectar y mitigar en runtime. LLM08 (excessive agency) es un problema de diseño — si el agente tiene demasiados permisos, un patch de runtime no lo arregla.

Tengo un post sobre OpenTelemetry en Next.js donde hablo de traces que sobreviven el edge. Ese tipo de observabilidad también ayuda acá: si no podés ver qué tools llamó el agente y con qué args, no podés auditar LLM08 en producción.

Checklist aplicado: el estado real de cada riesgo en mi pipeline

Riesgo	Estado encontrado	Acción tomada
LLM01 Prompt Injection	❌ Vulnerable	Zod schema en output de tools externas
LLM02 Insecure Output	⚠️ Parcial	Escaping explícito antes de render
LLM03 Training Data	🔵 Fuera de scope	Documentado como trust boundary
LLM04 Model DoS	⚠️ Sin límite	Agregué max iterations + log
LLM05 Supply Chain	⚠️ Invisible	`pnpm audit` en CI
LLM06 Info Disclosure	❌ Leaky prompts	Separé config de system prompt
LLM07 Plugin Flaws	⚠️ Parcial	Revisión de permisos por tool
LLM08 Excessive Agency	⚠️ Sin fricción	Confirm before execute en tools destructivas
LLM09 Overreliance	🔵 Proceso	Validación humana en nodos críticos
LLM10 Model Theft	⚠️ Prompts expuestos	Prompts a endpoint autenticado

❌ = hallazgo crítico | ⚠️ = mitigación parcial | 🔵 = fuera del control de la aplicación

FAQ

¿El OWASP LLM Top 10 aplica a agentes basados en Claude o GPT-4 vía API?

Sí, con matices. LLM01, LLM02, LLM06, LLM07, LLM08 y LLM10 son riesgos de la aplicación — aplican sin importar qué modelo uses. LLM03 (training data) y parte de LLM05 son riesgos del proveedor: si usás una API externa, los tomás como trust boundary. La auditoría empieza por los riesgos que sí podés controlar.

¿Con Zod alcanza para mitigar prompt injection?

No. Zod valida la estructura del output externo antes de que llegue al contexto — eso reduce la superficie, pero no elimina el riesgo. Un payload adversarial bien formado puede pasar la validación de schema. Zod es una capa, no una solución completa. La mitigación real combina schema validation, restricciones en el system prompt y revisión humana en puntos críticos.

¿Cline es seguro para usar en producción como orquestador de agentes?

Cline tiene acceso a filesystem, terminal y otras herramientas con efecto real. Eso no es inherentemente inseguro — es la funcionalidad que lo hace útil. El riesgo (LLM08) está en el diseño: si el agente puede ejecutar comandos destructivos sin confirmación humana, el riesgo es real independientemente de qué tan bien esté configurado Cline. La regla que aplico: cualquier tool con efecto irreversible requiere aprobación explícita.

¿Cada cuánto hay que correr esta auditoría?

Cada vez que cambiás la arquitectura del agente: agregás una tool nueva, cambiás el system prompt o modificás cómo el agente consume outputs externos. No es una auditoría de una sola vez — es un checklist que corre contra cada cambio estructural. Si agregás observabilidad (OpenTelemetry es una opción), podés detectar anomalías en runtime entre auditorías.

¿El OWASP LLM Top 10 cubre riesgos de multi-agente o solo agente único?

La versión actual (2025) cubre principalmente el riesgo por agente. En arquitecturas multi-agente, la superficie de LLM01 se multiplica: cada agente puede ser un vector de inyección para los demás. El framework nombra el riesgo, pero el detalle de mitigación para pipelines multi-agente queda en manos de cada equipo.

¿Qué riesgo debería atacar primero si tengo tiempo limitado?

LLM01 (prompt injection) si tu agente consume output externo — es el más explotable y el más ignorado. LLM08 (excessive agency) si el agente tiene acceso a herramientas con efecto irreversible — es el que más daño puede hacer en un fallo. Los demás dependen de tu stack, pero estos dos son el piso mínimo.

Conclusión: la diferencia entre leer y auditar

Mi postura es clara: el OWASP LLM Top 10 no sirve para leerlo y darlo por cubierto. Sirve para llevarlo a una sesión de revisión con el diagrama de arquitectura enfrente y preguntar, por cada riesgo, dónde exactamente en el pipeline eso puede fallar.

Lo que no compro es la idea de que "seguir las buenas prácticas" alcanza. Las prácticas son abstractas; el pipeline es concreto. En mi caso, LLM01 y LLM06 eran problemas reales que no habría encontrado sin hacer el ejercicio de auditoría sistemática. Los habría descubierto cuando alguien con motivación los explotara.

Si ya tenés agentes en TypeScript con MCP tools o system prompts elaborados, hacé el ejercicio: abrí el OWASP LLM Top 10, abrí el diagrama de arquitectura y preguntá riesgo por riesgo. El resultado va a ser más interesante que el listado.

Próximo paso concreto: tomá el checklist de esta tabla, reemplazá los estados con los propios y publicá los hallazgos. La auditoría que no se documenta no existe.

Fuente original:

OWASP LLM AI Security & Governance Checklist: https://owasp.org/www-project-top-10-for-large-language-model-applications/

Este artículo fue publicado originalmente en juanchi.dev

DEV Community: Juan Torchia

PyTorch: the deep learning framework that won the war

What it does

Why it's on the list

When NOT to use it

Wrapping up

PyTorch: el framework de deep learning que ganó la guerra

Qué hace

Por qué está en la lista

Cuándo NO usarlo

Cierre

TensorFlow: the ML elephant that's still standing

What it does

Why it made the list

When NOT to use it

TF is still standing, and there are reasons for that

TensorFlow: el elefante de ML que sigue en pie

Qué hace

Por qué está en la lista

Cuándo NO usarlo

TF sigue en pie, y hay razones para eso

Rate limiting in Next.js: what to protect before picking a library

Rate limiting in Next.js: what to protect before picking a library

Rate limiting in Next.js web apps: the missing mental model

Where the standard recipe breaks

The decision matrix before choosing a mechanism

What asset are you protecting?

What abuse pattern do you expect?

What does a false positive cost you?

How are you going to observe it?

Common mistakes and their real costs

Limits of this guide: what you can't conclude without your own data

FAQ: Rate limiting in Next.js

Conclusion: the policy before the library

Rate limiting en Next.js: qué proteger antes de elegir una librería

Rate limiting en Next.js: qué proteger antes de elegir una librería

Rate limiting en aplicaciones web Next.js: el modelo mental que falta

Dónde se rompe la receta estándar

La matriz de decisión antes de elegir el mecanismo

¿Qué activo protegés?

¿Qué patrón de abuso esperás?

¿Cuánto cuesta el falso positivo?

¿Cómo lo vas a observar?

Errores comunes y sus costos reales

Límites de esta guía: qué no podés concluir sin datos propios

FAQ: Rate limiting en Next.js

Conclusión: la política antes que la librería

npm Dependencies: How to Evaluate a Library Before Shipping It to Production

npm Dependencies: How to Evaluate a Library Before Shipping It to Production

Why Evaluating npm Dependencies Is a Maintenance Decision, Not Just a Security One

How to Audit a Dependency Before pnpm add

1. Check the Real State of the Repository

2. Analyze Transitive Dependencies with pnpm why

3. Run a Security Audit From the Start

4. Verify TypeScript Types

5. Evaluate Exit Cost With Your Own Interface

The Most Common Mistakes When Evaluating npm Dependencies

Mistake 1: Confusing Weekly Downloads With Stability

Mistake 2: Ignoring devDependencies in Projects With Build Steps

Mistake 3: Not Looking at peerDependencies

Mistake 4: Assuming a Small Package Is Safe

Decision Matrix: Do I Add This Dependency or Not?

What This Checklist Can't Guarantee

FAQ: Evaluating npm Dependencies in TypeScript Projects

My Take and the Next Concrete Step

Dependencias npm: cómo evaluar una librería antes de meterla en producción

Dependencias npm: cómo evaluar una librería antes de meterla en producción

Por qué evaluar dependencias npm es una decisión de mantenimiento, no solo de seguridad

Cómo auditar una dependencia antes de pnpm add

1. Revisar el estado real del repositorio

2. Analizar las dependencias transitivas con pnpm why

3. Correr una auditoría de seguridad desde el inicio

4. Verificar los tipos TypeScript

5. Evaluar el costo de salida con una interfaz propia

Los errores más comunes al evaluar dependencias npm

Error 1: Confundir descargas semanales con estabilidad

Error 2: Ignorar las devDependencies en proyectos con build steps

Error 3: No mirar el peerDependencies

Error 4: Asumir que un paquete pequeño es seguro

Matriz de decisión: ¿agrego esta dependencia o no?

How to Audit a Dependency Before `pnpm add`

2. Analyze Transitive Dependencies with `pnpm why`

Mistake 2: Ignoring `devDependencies` in Projects With Build Steps

Mistake 3: Not Looking at `peerDependencies`

Cómo auditar una dependencia antes de `pnpm add`

2. Analizar las dependencias transitivas con `pnpm why`

Error 2: Ignorar las `devDependencies` en proyectos con build steps

Error 3: No mirar el `peerDependencies`