Stash

Stash는 자사 이메일/비밀번호 인증, 무상태 Auth.js 세션, Prisma/PostgreSQL 영속성, Resend를 통한 트랜잭션 이메일, Model Context Protocol(MCP)을 통한 인증된 북마크 도구를 갖춘 Next.js App Router 애플리케이션입니다.

로컬 설정

1. pnpm install로 의존성을 설치합니다.

2. .env.example을 .env로 복사하고 모든 플레이스홀더를 교체합니다. .env는 절대 커밋하지 마세요.

3. pnpm exec auth secret(또는 다른 암호학적으로 안전한 생성기)으로 AUTH_SECRET을 생성합니다.

4. APP_URL을 신뢰할 수 있는 공개 오리진으로 설정합니다. 로컬에서는 보통 http://localhost:3000입니다. 프로덕션은 HTTPS를 사용해야 합니다.

5. Resend에서 검증된 도메인의 발신자로 EMAIL_FROM을 구성합니다.

6. MCP_AUTH_ISSUER를 신뢰할 수 있는 정확한 OAuth 인가 서버 발급자(issuer)로 설정합니다. 로컬 개발은 루프백 HTTP를 사용할 수 있지만, 프로덕션 발급자는 HTTPS를 사용해야 하며 쿼리나 프래그먼트를 포함할 수 없습니다.

7. pnpm prisma migrate dev로 마이그레이션을 적용합니다. 커밋된 마이그레이션은 인증 및 북마크 테이블을 생성합니다.

8. pnpm dev로 애플리케이션을 시작합니다.

서버는 DATABASE_URL, RESEND_API_KEY, AUTH_SECRET, APP_URL, MCP_AUTH_ISSUER, EMAIL_FROM을 검증하고, 값을 출력하지 않은 채 잘못된 변수 이름을 보고합니다.

Related MCP server: bookmark-mcp

인증 동작

• /signup은 자격 증명 사용자를 생성하고, 최선 노력(best-effort) 환영 이메일을 보내며, 사용자를 로그인시킵니다.

• /login은 7일간 유효한 암호화된 HTTP-only Auth.js 쿠키 세션을 생성합니다.

• /forgot-password는 유효한 이메일 구문에 대해 계정 열거에 저항하는 응답을 항상 반환합니다.

• /reset-password는 SHA-256 해시된 60분 단회용 토큰을 소비하고, 사용자의 세션 버전을 증가시켜 이전 세션을 폐기합니다.

• /은 렌더링 전에 DAL을 통해 현재 데이터베이스 레코드에 대해 인가합니다.

lib/rate-limit.ts는 향후 공유 IP/이메일 제한기의 확장 지점입니다. 데이터베이스 기반 60초 계정별 쿨다운은 그 자체로 완전한 프로덕션 남용 방지 시스템이 아닙니다.

북마크 MCP

무상태, 최신 전용 MCP 엔드포인트는 POST /api/mcp입니다. 표준 RFC 8707 리소스 식별자와 액세스 토큰 오디언스는 항상 ${APP_URL}/api/mcp입니다. 공개 RFC 9728 디스커버리는 /.well-known/oauth-protected-resource/api/mcp에서 제공되며, Stash는 인가, 토큰, 등록, 폐기, JWKS 엔드포인트를 제공하지 않습니다.

이 엔드포인트는 정확히 네 가지 도구를 노출합니다:

• add_bookmark 및 delete_bookmark는 bookmarks:write가 필요합니다.

• list_bookmarks 및 search_bookmarks는 bookmarks:read가 필요합니다.

동일 오리진 Stash 클라이언트는 Auth.js 쿠키를 사용할 수 있으며 두 기능을 모두 받습니다. 원격 네이티브, 데스크톱, 서버 클라이언트는 모든 요청에 베어러 액세스 토큰을 보냅니다. 브라우저 교차 오리진 MCP 호출은 의도적으로 지원되지 않습니다. 401 챌린지는 클라이언트를 보호된 리소스 문서로 안내하고, 403 insufficient_scope 챌린지는 제한된 OAuth 단계 상향(step-up)에 필요한 정확한 범위를 식별합니다.

Stash는 OAuth 2.1 보호 리소스일 뿐입니다. 별도로 운영되는 인가 서버는 PKCE S256이 있는 인가 코드, 정확한 canonical MCP URI에 대한 Resource Indicators, 인가 응답 발급자 식별을 지원해야 합니다. 또한 검증된 RFC 8414 또는 OpenID 디스커버리 메타데이터, jwks_uri, 그리고 허용된 비대칭 알고리즘(RS256 또는 ES256)을 포함하는 access_token_signing_alg_values_supported를 게시해야 합니다.

액세스 토큰은 보호 헤더 typ: at+jwt와 kid를 가진 단기 수명 JWT 액세스 토큰이어야 합니다. 필수 클레임은 정확한 iss, 정확한 단일 리소스 aud, 로컬 Stash 사용자 ID의 sub, exp, iat, 공백으로 구분된 scope, client_id(또는 azp), 정수 stash_session_version입니다. 인가 서버는 현재 Stash 사용자 행에서 해당 버전을 발행하고 토큰 수명을 60분 이하로 유지해야 합니다. sub에 이메일 주소를 넣거나 Stash가 토큰에서 사용자를 프로비저닝할 것으로 기대해서는 안 됩니다.

로컬 원격 클라이언트 테스트를 위해 루프백 인가 서버를 구성하고, MCP_AUTH_ISSUER를 해당 발급자로 설정하고, 클라이언트를 사전 등록하거나(또는 Client ID Metadata Document 사용) 정확한 ${APP_URL}/api/mcp 리소스와 최소 북마크 범위를 요청하고, 결과 액세스 토큰만 Stash에 보냅니다. 리프레시 토큰은 인가 서버에만 전송됩니다.

이메일 개발

자동화된 테스트는 Resend를 모킹하며 API를 호출하지 않습니다. 메일을 보내지 않고 템플릿을 미리 보려면 로컬 React 이메일 미리보기 도구나 비공개 개발 전용 하네스로 emails/의 내보낸 React 컴포넌트를 렌더링하세요. 공개 /api/send 엔드포인트를 추가하지 마세요. 종단 간 이메일 테스트에는 별도의 Resend 테스트 키/발신자와 받은 편지함을 사용하고, 프로덕션 수신자를 절대 사용하지 마세요.

검증

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

데이터베이스 통합 테스트는 격리된 TEST_DATABASE_URL이 필요합니다. 브라우저 테스트는 격리된 테스트 구성이 필요하며 pnpm test:e2e로 실행합니다. 두 스위트 모두 개발자 또는 프로덕션 데이터베이스를 가리키지 말고, 명시적 승인 없이 데이터베이스를 리셋하지 마세요.