Stash

Stash es una aplicación Next.js App Router con autenticación de correo electrónico/contraseña de primera parte, sesiones Auth.js sin estado, persistencia Prisma/PostgreSQL, correo electrónico transaccional a través de Resend y herramientas de marcadores autenticadas sobre Model Context Protocol (MCP).

Configuración local

1. Instala las dependencias con pnpm install.

2. Copia .env.example a .env y reemplaza cada marcador de posición. Nunca hagas commit de .env.

3. Genera AUTH_SECRET con pnpm exec auth secret (o con otro generador criptográficamente seguro).

4. Establece APP_URL al origen público de confianza, normalmente http://localhost:3000 en local. La producción debe usar HTTPS.

5. Configura EMAIL_FROM con un remitente en un dominio verificado en Resend.

6. Establece MCP_AUTH_ISSUER al emisor exacto y de confianza del servidor de autorización OAuth. El desarrollo local puede usar HTTP de bucle invertido; los emisores de producción deben usar HTTPS y no pueden contener una consulta o fragmento.

7. Aplica las migraciones con pnpm prisma migrate dev. Las migraciones confirmadas crean las tablas de autenticación y marcadores.

8. Inicia la aplicación con pnpm dev.

El servidor valida DATABASE_URL, RESEND_API_KEY, AUTH_SECRET, APP_URL, MCP_AUTH_ISSUER y EMAIL_FROM e informa los nombres de variables no válidos sin imprimir sus valores.

Related MCP server: bookmark-mcp

Comportamiento de autenticación

• /signup crea un usuario de credenciales, envía un correo de bienvenida de mejor esfuerzo e inicia la sesión del usuario.

• /login crea una sesión de cookie Auth.js cifrada, solo HTTP, de siete días.

• /forgot-password siempre devuelve una respuesta resistente a la enumeración de cuentas para una sintaxis de correo válida.

• /reset-password consume un token de un solo uso, con hash SHA-256, de 60 minutos, y revoca sesiones anteriores incrementando la versión de sesión del usuario.

• / autoriza contra el registro actual de la base de datos a través del DAL antes de renderizar.

lib/rate-limit.ts es el punto de extensión para un futuro limitador compartido de IP/correo. El enfriamiento de 60 segundos por cuenta respaldado por la base de datos no es un sistema completo de control de abuso en producción por sí solo.

Marcadores MCP

El endpoint MCP sin estado y exclusivamente moderno es POST /api/mcp. Su identificador de recurso canónico RFC 8707 y su audiencia de token de acceso son siempre ${APP_URL}/api/mcp. El descubrimiento público RFC 9728 está disponible en /.well-known/oauth-protected-resource/api/mcp; Stash no sirve endpoints de autorización, token, registro, revocación ni JWKS.

El endpoint expone exactamente cuatro herramientas:

• add_bookmark y delete_bookmark requieren bookmarks:write.

• list_bookmarks y search_bookmarks requieren bookmarks:read.

Los clientes Stash del mismo origen pueden usar su cookie Auth.js y recibir ambas capacidades. Los clientes remotos nativos, de escritorio y de servidor envían un token de acceso de portador en cada solicitud. Las llamadas MCP entre orígenes desde el navegador no son compatibles intencionalmente. Un desafío 401 dirige a los clientes al documento de recurso protegido; un desafío 403 insufficient_scope identifica el alcance exacto necesario para el aumento de privilegios OAuth acotado.

Stash es solo un recurso protegido OAuth 2.1. El servidor de autorización operado por separado debe admitir código de autorización con PKCE S256, Indicadores de Recurso para el URI MCP canónico exacto e identificación del emisor en la respuesta de autorización. Debe publicar metadatos de descubrimiento RFC 8414 u OpenID validados, un jwks_uri y access_token_signing_alg_values_supported que contenga un algoritmo asimétrico permitido (RS256 o ES256).

Los tokens de acceso deben ser tokens de acceso JWT de corta duración con encabezado protegido typ: at+jwt y un kid. Las reclamaciones requeridas son iss exacto, aud exacto de un solo recurso, ID de usuario local de Stash en sub, exp, iat, scope separado por espacios, client_id (o azp) y stash_session_version entero. El servidor de autorización debe acuñar esa versión a partir de la fila de usuario actual de Stash y mantener la vida del token en 60 minutos o menos. Nunca debe poner direcciones de correo electrónico en sub ni esperar que Stash aprovisione usuarios a partir de tokens.

Para probar clientes remotos en local, configura un servidor de autorización de bucle invertido, establece MCP_AUTH_ISSUER a su emisor, pre-registra el cliente (o usa un Documento de Metadatos de ID de Cliente), solicita el recurso exacto ${APP_URL}/api/mcp más los alcances de marcadores mínimos, y envía solo el token de acceso resultante a Stash. Los tokens de actualización van solo al servidor de autorización.

Desarrollo de correo electrónico

Las pruebas automatizadas simulan Resend y nunca llaman a su API. Para previsualizar plantillas sin enviar correos, renderiza los componentes React exportados en emails/ con una herramienta local de previsualización de correos de React o con un entorno de desarrollo privado exclusivo. No agregues un endpoint público /api/send. Para pruebas de correo de extremo a extremo, usa una clave/remitente y una bandeja de entrada de prueba de Resend separados; nunca uses destinatarios de producción.

Verificación

pnpm prisma format
pnpm prisma validate
pnpm prisma generate
pnpm lint
pnpm test
pnpm build

Las pruebas de integración de base de datos requieren un TEST_DATABASE_URL aislado. Las pruebas de navegador requieren configuración de prueba aislada y se ejecutan con pnpm test:e2e. Nunca apuntes ninguna de las suites a una base de datos de desarrollo o producción, y nunca restablezcas una base de datos sin aprobación explícita.