> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Módulo de almacenamiento

Un contrato ObjectStorage, adaptadores memory y compatible con S3.

## Guía paso a paso para principiantes

Requisitos previos: lea las dos guías para principiantes a continuación, finalice la configuración local web y abra este monorepo en la raíz de su editor. La configuración web pertenece a `apps/web/.env.local`; Next.js no lee la raíz `.env`. `/dashboard` en el modo falso predeterminado es una demostración sin base de datos; `/auth` necesita una base de datos migrada.

Términos breves: un espacio de trabajo son los usuarios, datos y configuraciones separados de un equipo. El servidor es el backend confiable; Mantenga las claves del proveedor fuera del código del navegador y del teléfono. Una migración es un cambio de base de datos versionada que crea o actualiza tablas. Un modelo de IA es el motor que responde; el catálogo de modelos es la lista del servidor de ID de modelos disponibles y precios. Un proveedor es un servicio externo, como inteligencia artificial, correo electrónico o servicio de facturación. Un derecho es una concesión que permite que un espacio de trabajo utilice una función. Un webhook es un mensaje que un servicio envía al URL de otro servicio.

1. Para una prueba sin credenciales, conserve `STORAGE_PROVIDER=memory`. Si esta caja no tiene control de carga visible, solicite a su agente de codificación que inspeccione `apps/web/app/api/storage/avatar/route.ts`, `apps/web/app/api/storage/logo/route.ts`, `apps/web/app/api/storage/organization-logo/route.ts` y la página de configuración correspondiente antes de cablear una pequeña imagen de muestra.

2. Para verificar la persistencia, configure `STORAGE_PROVIDER=s3`, `STORAGE_REGION` y `STORAGE_BUCKET` en `apps/web/.env.local`, agregue localmente las credenciales de prueba solo del servidor y reinicie.

3. La imagen debería recargarse desde el almacenamiento. Los archivos de memoria desaparecen cuando se reinicia el proceso; para errores de S3, verifique el depósito, el punto final y la política de acceso.

Para obtener código personalizado, comience con el `prompts/README.md` proporcionado y copie el mensaje más cercano: `prompts/new-app-screen.md` para una pantalla de aplicación o `prompts/new-landing-page.md` para una página pública. Para trabajos de servidor, base de datos o proveedor, asigne a su agente de codificación la tarea de esta guía y pídale que lea `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` y los espejos `.ai/` correspondientes; inspeccionar los archivos fuente exactos nombrados aquí; enumerar archivos y verificaciones antes de editarlos; preservar la propiedad del espacio de trabajo y los secretos exclusivos del servidor; y mostrarte la diferencia. Dígale el comportamiento que desea, los campos de entrada y salida, los roles permitidos, los éxitos y errores esperados y la cuenta, proveedor o dispositivo de prueba. Utilice valores de muestra; Nunca pegues un verdadero secreto.

[Antes de comenzar](https://supastack.dev/es/docs/web/before-you-start.md)

[Conceptos básicos de terminales](https://supastack.dev/es/docs/web/terminal-basics.md)

[Configuración local web](https://supastack.dev/es/docs/web/ship-in-5-minutes.md)

[Mensajes del agente y memoria del proyecto](https://supastack.dev/es/docs/web/agents.md)


## Selecciona el backend de almacenamiento

`STORAGE_PROVIDER=memory` es el valor predeterminado sin credenciales. `local` escribe objetos en disco bajo `STORAGE_LOCAL_DIR` (por defecto `./.data/storage`, obligatorio explícitamente en producción) y los transmite mediante URL con firma HMAC y caducidad en `/api/storage/local/[...key]` (`STORAGE_LOCAL_SIGNING_SECRET`, con respaldo en `AUTH_SECRET`) para despliegues de un solo servidor. `s3` utiliza `apps/web/src/storage-runtime.ts` para componer el cliente del SDK de AWS sobre el contrato reducido `@supastack/storage`, admitiendo Supabase Storage y MinIO con URL de estilo de ruta habilitadas por defecto.

```
STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_BUCKET=your-product-bucket
# Set STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY on the server.
# Optional: STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, STORAGE_PUBLIC_BASE_URL
# Self-hosted single-server disk storage:
# STORAGE_PROVIDER=local
# STORAGE_LOCAL_DIR=./.data/storage
# STORAGE_LOCAL_SIGNING_SECRET=
```


## Reutiliza los límites de carga

Las rutas incluidas cubren objetos, avatares, logotipos de perfil y logotipos de organización bajo `/api/storage/`. Resuelven la identidad y los permisos del espacio de trabajo y validan la forma de la carga antes del almacenamiento. Inspecciona la política de tamaño/tipo de la ruta elegida en lugar de aceptar claves de objeto arbitrarias del cliente.

Las URL públicas son para presentación, no para autorización. Mantén el contenido protegido detrás del límite de lectura verificada de la aplicación y configura la política del bucket/CDN para los datos de tu producto.


## Prueba el comportamiento del almacenamiento real

Prueba las cargas permitidas/denegadas, el rechazo de MIME y tamaño, rutas de otro espacio de trabajo, objetos ausentes y fallos del proveedor. El modo memoria no persiste entre procesos; verifica el almacenamiento y la recuperación con el backend seleccionado antes del lanzamiento.

[Configuración de almacenamiento Supabase](https://supastack.dev/es/docs/web/project-structure.md)

[Subir inventario de rutas](https://supastack.dev/es/docs/web/project-structure.md)


## Configuración y ajustes

packages/storage define la interfaz ObjectStorage — putObject, getObject y deleteObject contra locators de objetos — con MemoryObjectStorage para tests deterministas y S3CompatibleObjectStorage para buckets de producción.

Las claves de objeto se construyen con buildWorkspaceObjectKey y se comprueban con assertWorkspaceObjectKey, así que cada archivo almacenado está namespaced por workspace y propósito (avatar, archivo, logo). WorkspaceScopedStorageError se dispara cuando una clave escapa de su workspace.

```
interface ObjectStorage {
  putObject(input: PutObjectInput): Promise<StoredObject>
  getObject(locator: ObjectLocator): Promise<StoredObject | undefined>
  deleteObject(locator: ObjectLocator): Promise<boolean>
  getPublicUrl(locator: ObjectLocator): string
}

key = {workspaceId}/{purpose}/{safeName}
```


## Flujo de implementación

Las rutas de aplicación resuelven el workspace, validan la subida, construyen la clave con scope y llaman al adaptador — el storage nunca ve una ruta cruda del cliente. Selecciona el adaptador en el entorno del servidor a través de STORAGE_PROVIDER y sus credenciales.

Expón las lecturas a través del mismo límite de autorización; sirve URLs públicas solo para objetos que el producto publica deliberadamente.


## Verificación y solución de problemas

MemoryObjectStorage mantiene los tests unitarios deterministas — afirma claves, tipos de contenido y denegaciones entre workspaces ahí. Verifica el adaptador S3 a través de la ruta smoke opcional contra un bucket real antes de lanzar subidas.


## Siguiente

[Módulo de API](https://supastack.dev/es/docs/modules/api.md)