chore: bring flutter client, docs, deploy and tools into monorepo

docs/README.md

@@ -0,0 +1,45 @@
+# Musify — Documentación
+
+Musify es un backend de streaming de música: subir pistas, procesarlas (transcodificar el audio a `.m4a` y generar miniaturas), organizarlas en playlists y reproducirlas en streaming sin que los bytes pasen por la API.
+
+Esta carpeta explica **qué hace cada pieza, su propósito y por qué está diseñada así**.
+
+## Índice
+
+- [architecture.md](architecture.md) — Visión global: componentes, cómo encajan y los flujos principales.
+- [projects.md](projects.md) — Qué es y para qué sirve cada proyecto/solución.
+- [authentication.md](authentication.md) — Zitadel (OIDC), validación de JWT, provisioning/sync de usuarios.
+- [storage.md](storage.md) — SeaweedFS (S3), estructura de claves, URLs prefirmadas, qué es público y qué privado.
+- [streaming.md](streaming.md) — Streaming del audio (`.m4a` por HTTP range) con stream-ticket (RS256) y el reverse proxy (StreamingGateway).
+- [media-processing.md](media-processing.md) — El worker y los workflows de MassTransit (transcode de audio, miniaturas).
+- [development.md](development.md) — Cómo levantar todo en local: contenedores, puertos y comandos.
+
+## Mapa de componentes (alto nivel)
+
+```
+                 ┌─────────────────────────────────────────────┐
+   Cliente  ───► │ WebApi (:5111)  API REST + emite tickets     │
+                 └─────────────────────────────────────────────┘
+                        │ EF Core          │ presigned (subidas)   │ MassTransit (eventos)
+                        ▼                  ▼                       ▼
+                 PostgreSQL          SeaweedFS S3 (:8333)     RabbitMQ ──► Worker (procesa)
+                 (metadatos)         (objetos)                            audio→.m4a, imágenes
+                                          ▲
+   Cliente  ───► StreamingGateway (:8081) ┘   sirve audio .m4a (valida ticket, proxy al filer)
+
+   Login: Cliente ◄──► Zitadel (:8080, OIDC)   →  WebApi valida el JWT
+```
+
+## Stack
+
+- **.NET 10**, C#. Minimal APIs (WebApi), Worker Service (Worker), ASP.NET + YARP (StreamingGateway).
+- **CQRS** con [Mediator] (source-generator) y resultados con **Ardalis.Result**.
+- **EF Core 10** + **PostgreSQL** (metadatos).
+- **MassTransit 8** + **RabbitMQ** (procesado asíncrono con routing slips/sagas).
+- **SeaweedFS** (almacenamiento de objetos compatible con S3, vía AWSSDK.S3).
+- **ffmpeg** (transcode de audio a AAC/`.m4a`), **SixLabors.ImageSharp** (miniaturas).
+- **Zitadel** (OIDC/OAuth2) para identidad.
+
+## Repositorios git
+
+Cada proyecto de nivel superior es su propio repo git: `MusifyBackend`, `Musify.WebApi`, `Musify.StreamingGateway`, `Musify.Worker`. La raíz del workspace (`docs/`, `deploy/`, `player.html`) no está versionada.

docs/architecture.md

@@ -0,0 +1,55 @@
+# Arquitectura
+
+## Principios
+
+- **Clean architecture / capas** en `MusifyBackend`: el dominio y la aplicación no dependen de infraestructura; la infraestructura implementa las interfaces (`Application/Contracts`).
+- **CQRS**: cada operación es un `Command` o `Query` con su handler (Mediator). Los handlers devuelven `Ardalis.Result` (Ok/NotFound/Unauthorized/Conflict/Invalid…), que la WebApi traduce a códigos HTTP.
+- **Los bytes pesados no pasan por la API**: subidas con URLs prefirmadas (cliente → S3) y reproducción vía un reverse proxy dedicado (gateway → S3). La WebApi solo mueve metadatos y emite permisos.
+- **Procesado asíncrono**: crear una pista no transcodifica en caliente; publica un evento y un worker hace el trabajo pesado con compensación (sagas/routing slips de MassTransit).
+
+## Componentes
+
+| Componente | Responsabilidad | Por qué separado |
+|---|---|---|
+| **WebApi** | API REST (usuarios, pistas, playlists), autoriza, emite presigned URLs y stream-tickets | Punto de entrada fino; no procesa medios ni sirve bytes |
+| **MusifyBackend** | Dominio + casos de uso + infraestructura compartida (EF, S3, MassTransit, ffmpeg) | Lógica reutilizada por WebApi y Worker |
+| **StreamingGateway** | Reverse proxy (YARP) que valida el ticket y sirve el audio (`.m4a`) desde SeaweedFS | Escala con el tráfico de bytes, independiente de la API; SeaweedFS queda privado detrás |
+| **Worker** | Consume eventos de MassTransit: transcodifica audio a `.m4a` y genera miniaturas | Trabajo CPU/IO intensivo fuera del request HTTP |
+| **PostgreSQL** | Metadatos (usuarios, pistas, playlists, upload intents) | — |
+| **RabbitMQ** | Cola de eventos + outbox transaccional | Desacopla creación de procesado |
+| **SeaweedFS** | Almacenamiento de objetos (S3 + filer) | Guarda originales y derivados (audio `.m4a`, miniaturas) |
+| **Zitadel** | Identidad (OIDC/OAuth2) | Login y emisión de JWT |
+
+## Flujos principales
+
+### 1. Subida de una pista
+1. Cliente pide `POST /tracks/upload-urls` → la WebApi crea **UploadIntents** (reservas) y devuelve **URLs prefirmadas PUT** (imagen + audio).
+2. Cliente sube los ficheros **directo a SeaweedFS** con esas URLs (no pasan por la API).
+3. Cliente llama `POST /tracks` con los `intentId`s → la WebApi valida los intents, crea el `Track` (+ `UserHasTrack`) y publica `CreateTrackResourcesEvent`.
+4. El **Worker** consume el evento: mueve los originales a su sitio, genera miniaturas y transcodifica el audio a `.m4a`, y actualiza el estado del track.
+
+Ver detalle en [media-processing.md](media-processing.md) y [storage.md](storage.md).
+
+### 2. Reproducción (streaming)
+1. Cliente pide `GET /tracks/{id}/stream` (autenticado) → la WebApi autoriza y devuelve `{ manifestUrl, ticket }` (URL al `.m4a` + ticket RS256 acotado a la carpeta de esa pista).
+2. El reproductor abre la URL del audio añadiendo `?t=<ticket>` (o cabecera `X-Stream-Ticket`) y descarga por HTTP range.
+3. El **StreamingGateway** valida el ticket y reenvía al filer de SeaweedFS; los bytes van storage → cliente.
+
+Ver [streaming.md](streaming.md).
+
+### 3. Autenticación
+1. Cliente hace login OIDC contra **Zitadel** y obtiene un access token (JWT).
+2. La WebApi valida la firma/iss/aud del JWT.
+3. En cada token validado, se **sincroniza** el usuario local (crea/actualiza nombre y foto) — provisioning just-in-time.
+
+Ver [authentication.md](authentication.md).
+
+## Modelo de datos (entidades)
+
+- **User** — `Id` es el `sub` numérico de Zitadel (`long`), más nombre y `ProfilePictureUrl`.
+- **Track** — pista: nombres de originales/derivados, `AudioFolderName` (carpeta del `.m4a` transcodificado), estados de procesado (`ProcessingStatus`), `LifeCycleStatus`.
+- **PlayList** — lista del usuario (`UserId`).
+- **PlayListHasTrack** — pistas dentro de una playlist (con `Position`).
+- **UserHasTrack** — propiedad: qué usuario posee qué pista.
+- **UploadIntent** — reserva de subida (clave, bucket, tamaño esperado, estado, expiración) para validar y aplicar cuota.
+- **Upload** — registro de objetos subidos/transferidos al storage.

docs/authentication.md

@@ -0,0 +1,40 @@
+# Autenticación e identidad
+
+## Proveedor: Zitadel (OIDC/OAuth2)
+
+El login y la emisión de tokens los hace **Zitadel** (no la WebApi). La WebApi es un **resource server**: solo **valida** el access token (JWT) que le llega en `Authorization: Bearer`.
+
+- Config en la sección `Authentication` (`AuthenticationConfiguration`): metadata address, issuer, audience, client id, endpoints de authorize/token, scopes.
+- `JwtBearerOptionsSetup` configura la validación (issuer, audience, claves vía metadata OIDC).
+- En dev, `RequireHttpsMetadata = false`.
+
+### Requisito clave en la app de Zitadel
+- **Auth Token Type = JWT** (si no, Zitadel emite un token **opaco** sin puntos y `JwtBearer` no lo puede validar → 401 en todo lo protegido).
+- **User Info inside Token** activado si quieres que el access token traiga claims de perfil (`name`, `email`, `picture`). Por defecto el access token es mínimo (`sub`, `aud`, `iss`, `exp`…), sin perfil.
+
+## El `sub` es numérico → `User.Id` es `long`
+
+El `sub` de Zitadel es un entero de 64 bits en string (p. ej. `371953080444977155`), **no un GUID**. Por eso:
+- `User.Id` y todas las FKs de usuario (`PlayList.UserId`, `UserHasTrack.UserId`, `UploadIntent.UserId`) son **`long`**.
+- `User.Id` lleva `[DatabaseGenerated(None)]` para que EF **no** lo autogenere: se asigna el `sub`.
+- `CurrentUser.Id` es `long?` (parsea con `long.TryParse`); `RequiredId` lanza si falta.
+
+**Por qué**: el código antiguo hacía `Guid.Parse(sub)` y reventaba (FormatException) → 401 en cada endpoint protegido. Se decidió guardar el `sub` tal cual como número.
+
+## Provisioning / sincronización de usuarios
+
+En cada token validado, `JwtBearerEventsHandler.TokenValidated`:
+1. Lee `sub` (id), `name`/`preferred_username`/`email` (con fallback) y el claim OIDC `picture`.
+2. Envía un `SyncUserCommand`.
+
+`SyncUserCommandHandler` hace un **upsert idempotente**:
+- Si el usuario no existe → lo crea.
+- Si existe → actualiza nombre/apellidos/`ProfilePictureUrl` **solo si cambiaron** (escribe en DB únicamente cuando hay cambios).
+
+**Por qué upsert con "escribe solo si cambió"**: `TokenValidated` se ejecuta en **cada request**; sin ese guardado condicional estaríamos escribiendo en cada petición. Y debe ser resiliente: si el provisioning falla, se loguea pero **no** tumba la autenticación.
+
+> Nota: `CreateUserCommand` (endpoint manual `POST /users`) sigue siendo create-only; el sync del login usa `SyncUserCommand`.
+
+## Foto de perfil
+
+`User.ProfilePictureUrl` se rellena desde el claim `picture` del token. Si Zitadel no mete la info de perfil en el access token (ver arriba), llega `null` — el código es correcto, pero no hay nada que sincronizar hasta activar esa opción.

docs/development.md

@@ -0,0 +1,91 @@
+# Entorno de desarrollo
+
+Cómo levantar todo en local y probarlo.
+
+## Dependencias (Docker)
+
+```powershell
+# SeaweedFS (almacenamiento)
+docker compose -f deploy\seaweedfs\docker-compose.yml up -d
+
+# PostgreSQL + pgAdmin
+docker compose -f "C:\Users\XShin\OneDrive\Desktop\postgresql\docker-compose.yml" up -d
+
+# Zitadel (auth)
+docker compose -f "C:\Users\XShin\OneDrive\Pictures\zitadel-compose\docker-compose.yml" up -d
+
+# RabbitMQ (contenedor suelto)
+docker start rabbitmq
+```
+
+> Nota: usa `docker compose up` (no `docker start`) para Postgres/Zitadel: si sus redes se borraron, compose las recrea.
+
+## Aplicaciones (.NET)
+
+```powershell
+dotnet run --project Musify.WebApi\WebApi                    # :5111
+dotnet run --project Musify.StreamingGateway\StreamingGateway # :8081
+dotnet run --project Musify.Worker\Worker                     # background
+```
+
+## Mapa de puertos
+
+| Servicio | Puerto |
+|---|---|
+| WebApi | 5111 (`/scalar/v1`, `/openapi/v1.json`) |
+| StreamingGateway | 8081 (`/health`, `/media/...`) |
+| SeaweedFS S3 / filer / master | 8333 / 8888 / 9333 |
+| Zitadel | 8080 |
+| PostgreSQL | 59000 (→ 5432 en el contenedor) |
+| RabbitMQ AMQP / management | 5672 / 15672 |
+| pgAdmin | 5050 |
+
+DB: `musify_db`, usuario `postgres`/`postgres`. Bucket S3: `webapi-storage` (credenciales `admin_access_key`/`admin_secret_key`).
+
+## Migraciones
+
+No hay migración automática al arrancar. Para aplicar cambios de esquema:
+
+```powershell
+cd MusifyBackend\Infrastructure
+dotnet ef database update --context Database
+```
+
+La cadena de conexión para `dotnet ef` se lee de `DesignSettings.json` / user-secrets del proyecto Infrastructure.
+
+## Stream-tickets (claves RS256)
+
+La WebApi firma los stream-tickets con una clave privada y el gateway valida con la pública:
+
+```powershell
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out stream_private.pem
+openssl rsa -in stream_private.pem -pubout -out stream_public.pem
+```
+
+- WebApi: `StreamTicket:PrivateKeyPath` → `stream_private.pem`.
+- Gateway: `StreamTicket:PublicKeyPath` → `stream_public.pem`.
+
+## Consola de pruebas: `player.html`
+
+Un único archivo HTML para probar todo sin front:
+
+1. Sírvelo o ábrelo directo (el CORS está abierto en Development).
+2. Pega tu **access token** de Zitadel y la API base (`http://localhost:5111`).
+3. Permite: crear/actualizar/eliminar playlists, listar canciones, añadir/quitar canciones de una playlist, ver las canciones de una playlist y **reproducir** (pide el ticket y abre el `.m4a` con `?t=<ticket>`).
+
+> Nota: `player.html` todavía usa dash.js; tras el cambio a `.m4a` debe actualizarse para reproducir el fichero directo (elemento `<audio>` por HTTP range).
+
+Para obtener un token: login OAuth2 en Scalar (`/scalar/v1`) o cópialo de DevTools.
+
+## Config (AppSettings)
+
+Convención: `AppSettings.json` = plantilla con valores vacíos/por defecto; `AppSettings.Development.json` = valores reales de dev. Secretos sensibles (claves, connection strings) van idealmente en user-secrets.
+
+Secciones clave: `Authentication` (Zitadel), `Database`, `MassTransit`, `InfrastructureStorage` (S3), `ApplicationStorage` (bucket), `Track`, `PlayList`, `UploadIntent`, `AudioTranscoder`, `Workers`, `StreamGateway`/`StreamTicket`.
+
+## Requisitos del host
+
+- .NET 10 SDK.
+- **ffmpeg** en el PATH (transcode de audio del Worker).
+- Docker Desktop.
+- Directorio temporal de trabajo del Worker (`Workers:Routes:TemporaryFilesDirectory`, p. ej. `D:\tempsFilesDev`).

docs/media-processing.md

@@ -0,0 +1,46 @@
+# Procesado de medios (Worker + MassTransit)
+
+El procesado pesado (transcode de audio, miniaturas, transferencias en el bucket) ocurre **fuera del request HTTP**, en el **Worker**, orquestado con **MassTransit** sobre RabbitMQ.
+
+## Por qué asíncrono y con routing slips
+
+- Transcodificar audio y redimensionar imágenes es CPU/IO intensivo: no debe bloquear una llamada a la API.
+- Es un proceso **multi-paso con efectos secundarios** (descargar de S3 → transcodificar → subir resultados → actualizar DB). Si un paso falla, hay que **deshacer** los anteriores. Para eso se usan **routing slips** (patrón Saga de MassTransit): cada paso es una *activity* con su **compensación**.
+- **Outbox transaccional** (EF + MassTransit): el evento se publica de forma consistente con el cambio en la DB (no se pierde ni se duplica).
+
+## Disparo
+
+Al crear/actualizar una pista o playlist, el handler publica un evento (p. ej. `CreateTrackResourcesEvent`). Un **consumer** (`CreateTrackConsumer`, `UpdateTrackPictureConsumer`, …) construye un **routing slip** con la secuencia de activities y lo lanza.
+
+## Builders de routing slip
+
+- `CreateTrackRoutingSlipBuilder` — alta de pista (consume intents, mueve ficheros, dispara procesado).
+- `PictureWorkflowRoutingSlipBuilder` — pipeline de imágenes (descargar → redimensionar → subir → actualizar).
+- `AudioWorkflowRoutingSlipBuilder` — pipeline de audio (descargar → transcodificar a `.m4a` → subir carpeta → actualizar).
+- `DeleteTrackRoutingSlipBuilder`, `DeletePlayListRoutingSlipBuilder`, `PlayListPictureSourceRoutingSlipBuilder`.
+
+## Activities (pasos)
+
+Agrupadas por área:
+- **Files**: `DownloadFileFromBucketActivity`, `UploadFileToBucketActivity`, `TransferFilesToBucketActivity`, `CopyFileInBucketActivity`, `RemoveFileFromBucketActivity`.
+- **Audio**: `GenerateAudioWorkflowPathsActivity`, `TranscodeAudioActivity` (ffmpeg → `.m4a`), `UpdateTrackAudioActivity` (guarda `AudioFolderName` y marca `Completed`).
+- **Pictures**: `GeneratePictureWorkflowPathsActivity`, `ResizePictureActivity` (ImageSharp), `UpdateTrackPictureActivity`, `UpdatePlayListPictureActivity`.
+- **Tracks/PlayLists**: `MarkTrackAsRemovingActivity`, `DeleteTrackFromDbActivity`, `PublishTrackProcessingEventsActivity`, y equivalentes de playlist.
+- **UploadIntents**: `ConsumeUploadIntentsActivity`.
+
+`RoutingSlipCleanUpConsumer` reacciona a `Completed`/`Faulted` para limpiar (p. ej. borrar el directorio temporal de trabajo).
+
+## Transcode de audio
+
+`AudioTranscoderService` invoca **ffmpeg** leyendo el original por stdin y produciendo en un directorio de trabajo un único `audio.m4a`: AAC con codec/bitrate/sample-rate/profile configurables y `-movflags +faststart` (moov al inicio → seek por range). Luego `TransferFilesToBucketActivity` sube esa carpeta a `Tracks/ProcessedAudios/{folder}/` y `UpdateTrackAudioActivity` guarda el `AudioFolderName` (la carpeta **de destino en S3**, no la local) y pone el estado en `Completed`.
+
+## Configuración que necesita el Worker
+
+El Worker registra: storage (S3), transcoder (ffmpeg), pictures, DB, los consumers de MassTransit y los jobs de upload intents. Su `AppSettings` debe tener las secciones correctas: `Bucket` (= `webapi-storage`, el mismo que la API), `PlayList`, `Track`, `MassTransit`, `AudioTranscoder`, `UploadIntent`, `Workers` (directorio temporal), `InfrastructureStorage`, `Database`.
+
+## Jobs de fondo
+
+- `UploadIntentExpirationJob` — marca intents caducados como expirados (libera cuota) cada `ExpirationJobIntervalSeconds`.
+- `TemporalUploadsCleanUpJob` — limpia subidas temporales antiguas.
+
+Corren en el host del Worker (`AddUploadIntentJobs`). Si no se registran en ningún proceso, los intents colgados no se limpian solos.

docs/projects.md

@@ -0,0 +1,59 @@
+# Proyectos
+
+Cada carpeta de nivel superior es una solución/repo independiente.
+
+## Musify.WebApi/WebApi  (`:5111`)
+
+API REST pública (Minimal APIs, .NET 10). Es la fachada fina del sistema.
+
+- **Endpoints**: `UserEndpoints`, `TrackEndpoints`, `PlayListEndpoints`.
+- **Autenticación**: JWT Bearer contra Zitadel (`Authentication/`), con `JwtBearerEventsHandler` que sincroniza el usuario en cada token validado.
+- **`CurrentUser`**: abstracción que se enlaza como parámetro de endpoint (`IBindableFromHttpContext`) y expone los claims básicos (`Id` como `long?`, `RequiredId`, nombre, etc.) sin tener que leer `ClaimsPrincipal` a mano.
+- **Emite**: presigned URLs de subida (vía `IStorageService`) y **stream-tickets** (vía `IStreamTicketService`, RS256).
+- **OpenAPI + Scalar** para documentación/prueba; OAuth2 (PKCE) configurado para login desde Scalar.
+- **CORS** totalmente abierto **solo en Development** (para el `player.html` y front local).
+- Traduce `Ardalis.Result` → HTTP en `ResultHttpExtensions`.
+
+**Propósito/porqué**: separar la cara pública (autorización + metadatos) del procesado y del servido de bytes.
+
+## MusifyBackend  (Domain + Application + Infrastructure)
+
+El núcleo, en tres proyectos (clean architecture):
+
+### Domain
+Entidades (`Entities/`) y value objects/enums (`ValueObjects/`: `ProcessingStatus`, `LifeCycleStatus`, `UploadIntentStatus`, …). Sin dependencias de infraestructura.
+
+### Application
+Casos de uso (CQRS con Mediator):
+- `Tracks/`, `PlayLists/`, `Users/` → `Commands`, `Queries`, `Handlers`, `Responses`.
+- `Contracts/` → interfaces que implementa la infraestructura (`IDatabase`, `IStorageService`, `IAudioTranscoderService`, `IPictureService`, `IEventBus`, `IStreamTicketService`).
+- `Configuration/` → opciones tipadas (Track, PlayList, ApplicationStorage, UploadIntent…) bindeadas y validadas al arranque.
+- `Shared/` → helpers transversales (`StorageKey.Combine`, `ImageSize`).
+- `Pagination/` → `PaginatedResponse<T>`.
+
+**Porqué**: la lógica de negocio no conoce EF, S3 ni RabbitMQ; solo interfaces. Reutilizable por WebApi y Worker.
+
+### Infrastructure
+Implementaciones concretas:
+- `Persistence/` → `Database` (EF Core/Npgsql), migraciones.
+- `Services/` → `StorageService` (AWSSDK.S3 contra SeaweedFS), `AudioTranscoderService` (ffmpeg → `.m4a`), `PictureService` (ImageSharp), `StreamTicketService` (firma RS256).
+- `MassTransit/` → consumers, activities y routing slips (ver [media-processing.md](media-processing.md)).
+- `Jobs/` → `UploadIntentExpirationJob`, `TemporalUploadsCleanUpJob`.
+
+## Musify.StreamingGateway/StreamingGateway  (`:8081`)
+
+Reverse proxy (ASP.NET + **YARP**) que sirve el audio (`.m4a`) desde SeaweedFS. Valida el stream-ticket (RS256, clave pública) y, si el objeto pedido cae bajo el prefijo autorizado, reenvía al filer.
+
+**Porqué un proyecto aparte**: escala con el tráfico de bytes independientemente de la API, tiene superficie mínima (solo sabe validar un JWT y proxiar) y permite que SeaweedFS quede en red privada. Ver [streaming.md](streaming.md).
+
+## Musify.Worker/Worker
+
+Worker Service (host de fondo) que consume los eventos de MassTransit y ejecuta el procesado pesado: transcode de audio a `.m4a` (ffmpeg), generación de miniaturas (ImageSharp), transferencias de ficheros en el bucket, y los jobs de expiración/limpieza de upload intents.
+
+**Porqué aparte**: el trabajo CPU/IO no debe ocurrir dentro de un request HTTP; se escala y reinicia por separado. (Antes se llamaba `Musify.PictureWorker`; se renombró porque hace más que imágenes.)
+
+## Raíz del workspace (no versionada)
+
+- **`deploy/seaweedfs/`** — `docker-compose.yml` + `s3.conf` para levantar SeaweedFS.
+- **`player.html`** — consola de pruebas (un solo archivo): login con token, CRUD de playlists, añadir/quitar canciones, listar y reproducir. Ver [development.md](development.md). (Pendiente: hoy usa dash.js; con el cambio a `.m4a` debe reproducir el fichero directo por `<audio>`/range.)
+- **`docs/`** — esta documentación.

docs/storage.md

@@ -0,0 +1,48 @@
+# Almacenamiento (SeaweedFS / S3)
+
+## Qué es
+
+**SeaweedFS** es el almacén de objetos, compatible con la API S3. Guarda los originales subidos y los derivados (audio `.m4a`, miniaturas). Se accede vía `AWSSDK.S3` desde `StorageService` (`IStorageService`).
+
+Expone:
+- **S3 API** (`:8333`) — operaciones S3 (presigned URLs, put/get/list…).
+- **filer HTTP** (`:8888`) — sirve los ficheros por ruta; lo usa el **StreamingGateway**.
+- master (`:9333`) y volume server — internos.
+
+Bucket de la app: **`webapi-storage`** (`ApplicationStorage:Bucket`). Importante: la WebApi y el Worker usan **el mismo bucket** (el worker procesa lo que sube la API).
+
+## Estructura de claves (layout)
+
+- `temp/{userId}/Tracks/{guid}.{ext}` — subidas temporales (objetivo de las presigned PUT, antes de consumir el intent).
+- `uploads/{userId}/Tracks/OriginalPictures|OriginalAudios/...` — originales ya consumidos.
+- `Tracks/SmallPictures|MediumPictures|LargePictures/...` — miniaturas generadas.
+- `Tracks/ProcessedAudios/{AudioFolderName}/` — audio transcodificado (`audio.m4a`, AAC con faststart).
+
+Las claves se construyen **siempre** con el helper `StorageKey.Combine(...)` (en `Application/Shared`), que une segmentos con `/` limpiando espacios y barras. Está centralizado para estandarizar y no repetir lógica.
+
+> En el filer, los objetos S3 viven bajo `/buckets/{bucket}/{key}` — de ahí que el gateway reescriba `/media/{key}` → `/buckets/webapi-storage/{key}`.
+
+## URLs prefirmadas (presigned)
+
+Para **no** hacer pasar ficheros grandes por la API, el cliente habla directo con S3 mediante URLs firmadas de corta vida:
+
+- **Subidas (PUT)**: `RequestTrackUploadUrls` / `RequestPlayListPictureUpload` generan presigned PUT (con `Content-Type` y `If-None-Match: *` firmados, expiración ~120s). El cliente sube directo a S3.
+- **Imágenes (GET)**: las miniaturas se sirven con presigned GET (un objeto = una URL).
+
+**Por qué presigned y no proxiar**: subir un audio de ~100 MB a través de la API consumiría memoria/ancho de banda de los servidores de aplicación y escalaría mal. La presigned PUT directa a S3 es el patrón estándar y correcto.
+
+### Upload intents y cuota
+Cada `upload-urls` crea **UploadIntents** (reservas en estado `Issued`) y devuelve las URLs. Al crear la pista/playlist se **consumen**. Hay cuota por usuario (`MaxActiveUploadIntentsPerUser`, bytes…) para evitar abuso. El `UploadIntentExpirationJob` (en el Worker) marca como expirados los intents caducados y libera la cuota; si ese job no corre, los intents colgados se acumulan y bloquean nuevas subidas.
+
+## Qué es público y qué privado (despliegue)
+
+| Exponer a internet | Mantener privado |
+|---|---|
+| S3 API `:8333` (tras TLS) — necesario para presigned PUT/GET del cliente | filer `:8888` (solo el gateway, en red interna) |
+| StreamingGateway `:8081` | master `:9333`, volume server, UI de admin |
+
+- **El audio** se sirve por el gateway → SeaweedFS puede quedar privado para ese flujo.
+- **Subidas e imágenes** usan presigned → el cliente toca el endpoint S3 directamente, así que `:8333` debe ser alcanzable (pero inútil sin firma válida; es el modelo de cualquier bucket S3/MinIO).
+- En **producción**: `InfrastructureStorage:Address` debe ser el **endpoint S3 público** (la firma se calcula para ese host); si los servidores no lo alcanzan internamente, se usa config dividida (host público para firmar / interno para operaciones server-side).
+
+**Regla**: el gateway y, como mucho, el `:8333` firmado son la única superficie pública; master/volume/filer/admin **nunca** se exponen.

docs/streaming.md

@@ -0,0 +1,55 @@
+# Streaming de audio
+
+## Objetivo
+
+Reproducir el audio **sin que los bytes pasen por la WebApi**, pero con control de acceso. La WebApi solo emite un permiso corto; el reverse proxy sirve los bytes desde SeaweedFS.
+
+## Formato: fichero único AAC (.m4a) por HTTP range
+
+El audio se transcodifica a **un único `audio.m4a`** (AAC, contenedor MP4 con `+faststart` para que el átomo `moov` quede al inicio y el seek por range funcione), dentro de la carpeta `Tracks/ProcessedAudios/{AudioFolderName}/`. No hay manifest ni segmentos: el reproductor descarga el fichero por **HTTP range requests** (modelo tipo Spotify para VOD musical).
+
+Multi-bitrate no está implementado hoy; el camino para añadirlo es transcodificar varias calidades (`audio_96.m4a`, …) y que el cliente elija una al iniciar (sin ABR fluido a mitad de pista, igual que Spotify).
+
+## El acceso: stream-ticket de prefijo
+
+Se autoriza **el prefijo de la carpeta** de la pista con un *stream-ticket* de corta vida, y el proxy lo valida en cada petición. Aunque hoy sea un único objeto, el ticket sigue acotado al prefijo `Tracks/ProcessedAudios/<folder>/` (cubre el fichero actual y cualquier calidad futura).
+
+## Flujo
+
+1. `GET /tracks/{id}/stream` (autenticado) → la WebApi autoriza y devuelve:
+   ```json
+   { "manifestUrl": "http://<gateway>/media/Tracks/ProcessedAudios/<folder>/audio.m4a",
+     "ticket": "<JWT RS256>", "expiresInSeconds": 3600 }
+   ```
+   El ticket lleva el claim `prefix = "Tracks/ProcessedAudios/<folder>/"`.
+2. El reproductor abre la URL del audio añadiéndole `?t=<ticket>` (o la cabecera `X-Stream-Ticket`).
+3. El **StreamingGateway** (YARP) valida el ticket y reenvía al filer; los bytes van SeaweedFS → cliente (con range/seek).
+
+## El ticket (RS256)
+
+- Lo firma la WebApi con clave **privada** (`StreamTicketService`); el gateway valida con la **pública** (`TicketValidator`). Así el gateway **no puede emitir** tickets, solo verificarlos.
+- Claims: `sub`, `prefix`, `aud = media-gateway`, `iss = musify-webapi`, `exp` (TTL ~1h).
+
+**Por qué RS256 (asimétrica)**: separa responsabilidades — emisor (WebApi) y verificador (gateway) no comparten secreto; el gateway, aunque se comprometa, no puede crear permisos.
+
+## El gateway (validación + proxy)
+
+`TicketValidationMiddleware` en cada petición a `/media/**`:
+1. Lee `?t=`, valida firma/aud/iss/exp.
+2. Comprueba que la clave pedida **empieza por** el `prefix` del ticket (`StartsWith`). Si no → 403.
+3. Quita el `?t=` y deja pasar a YARP, que reescribe `/media/{key}` → `/buckets/webapi-storage/{key}` del filer.
+
+- Sin ticket → **401**; fuera de prefijo → **403**; ok → **200** (y **206** en range requests, así que el seek funciona).
+- Pasa `Range`/`Accept-Ranges` y expone esos headers por CORS.
+
+## ¿Un ticket por canción?
+
+Sí. Cada ticket está acotado a **una** carpeta (una pista). Para reproducir otra, se pide otro ticket. Es barato (la WebApi solo firma un JWT) y es lo más seguro: cada permiso abre solo lo que vas a reproducir.
+
+- Si algún día molesta (muchísimos cambios de pista), el mismo mecanismo del claim `prefix` permite ampliar el alcance: a nivel de playlist o de toda la biblioteca (`Tracks/ProcessedAudios/`). Trade-off seguridad ↔ comodidad. Por defecto, **por canción**.
+
+## Pendiente / notas de seguridad
+
+- La política de quién puede pedir el ticket es hoy "cualquier autenticado" (TODO: restringir con `UserHasTrack`/visibilidad).
+- El check de prefijo es `StartsWith` literal; conviene endurecer rechazando claves con `..` (path traversal), aunque navegadores y ASP.NET normalizan `..`.
+- El ticket viaja en la query (`?t=`); el gateway lo elimina antes de reenviar (no llega a los logs del filer).