f64a80ba2a
Closes out the fix-auth-bypass convoy (PRs #6–#11, merged through
1629afb) on the docs side. Code already on main; this PR is docs only.
Updates:
AGENTS.md
- §1 auth bullet refreshed (auth-secret SoT, 24h TTL, no synthetic
admin, login/register rate limit)
- §3 conventions point at lib/auth-secret.js + lib/rate-limit.js
- §4 gotchas #2/#3/#5 converted to "Resolved" notes in place
(NOT renumbered, to preserve cross-references)
- new #12 documents the KV_REST_API_* env-var convention
- §5 setup list adds the rate-limit env vars
- §6 testing rewritten for Vitest (16 unit tests, blocking CI gate)
.cursor/rules/auth-and-permissions.mdc
- canonical-surface table gains lib/auth-secret.js + lib/rate-limit.js
- token model now 24h (was 7d) with fail-loud explanation
- server-side authorization patterns lead with null → 401 contract
.cursor/rules/api-routes.mdc
- removes the "CRITICAL — known bug" callout (resolved by Brief 2)
- adds a "Rate limiting" section with verbatim shape + env-var notes
- "Dev/test endpoints" → "Removed" historical note so future agents
searching for test-db understand why it's gone
.convoys/fix-auth-bypass.md (restored — was on convoy branch only)
- frontmatter → status: shipped
- new "Convoy outcome" section: briefs + commits + resolved gotchas,
R1-R12 risk walk, env-var-rename deviation record, queued follow-up
convoys, lessons learned
.convoys/fix-auth-bypass/brief-{1..5}-*.md (restored from convoy branch)
- audit-trail completeness; convoy plan references them by name
- brief 4 additionally updated: UPSTASH_REDIS_REST_* → KV_REST_API_*
across init rules, smoke, pre-deploy checklist
- brief 4 has a new "Post-merge addendum" explaining the rename
.convoys/ship-readiness.md
- P0 #1, #2, #4 → RESOLVED with merge-commit citations
- P0 #5 (CORS), #6 (rate limit) → PARTIAL with deferral pointers
(cors-tighten and add-rate-limiting convoys)
- each item gains an "As-shipped" line for self-containment
README.md
- Next.js 15 → 16, TypeScript claim corrected to JS-with-devDep
- auth + rate-limit + testing bullets updated
- env-var template extended with KV_REST_API_*
- deleted dev-endpoints note added to the API list
- "Default Admin Account" section LEFT ALONE — drop-public-setup territory
Verified: build exit 0 (with JWT_SECRET set), 16/16 vitest tests pass,
lint baseline unchanged (128/81/47).
Convoy: fix-auth-bypass / role-doc-writer (closeout)
Co-authored-by: Cursor <cursoragent@cursor.com>
130 lines
No EOL
4 KiB
Markdown
130 lines
No EOL
4 KiB
Markdown
# TCG Vault
|
|
|
|
A modern trading card game collection manager built with Next.js and Neon Database.
|
|
|
|
## 🚀 Features
|
|
|
|
- **Card Management**: Track your MTG, Pokémon, and Lorcana cards
|
|
- **Collection Organization**: Create and manage card collections
|
|
- **Deck Building**: Build and share decks
|
|
- **Authentication**: Secure user accounts with JWT
|
|
- **Admin Panel**: Manage cards and users
|
|
- **Real-time Pricing**: Track card values
|
|
|
|
## 🛠️ Tech Stack
|
|
|
|
- **Frontend**: Next.js 16 (Pages router), React 18, JavaScript (TypeScript is a devDep only — see `AGENTS.md` Gotcha #9)
|
|
- **Backend**: Next.js API Routes
|
|
- **Database**: Neon PostgreSQL (serverless)
|
|
- **Authentication**: JWT with bcrypt (24-hour expiry; `lib/auth-secret.js` is the single source of truth for `JWT_SECRET`)
|
|
- **Rate limiting**: `@upstash/ratelimit` on `/api/auth/login` + `/api/auth/register` (5 attempts / 15 min per IP)
|
|
- **Testing**: Vitest (unit); Playwright queued
|
|
- **Styling**: Tailwind CSS
|
|
- **Deployment**: Vercel
|
|
|
|
## 📦 Installation
|
|
|
|
1. **Clone the repository**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd tcg-vault
|
|
```
|
|
|
|
2. **Install dependencies**
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Set up environment variables**
|
|
```bash
|
|
cp .env.example .env.local
|
|
```
|
|
|
|
Update `.env.local` with your Neon database URL and a real JWT secret:
|
|
```env
|
|
POSTGRES_URL="postgresql://your-username:your-password@your-host/your-database"
|
|
JWT_SECRET="<generate with: openssl rand -hex 32>"
|
|
# Optional — exercise the rate limiter locally. Without them, `lib/rate-limit.js`
|
|
# warn-and-no-ops in dev. In production these are auto-provisioned by the
|
|
# Vercel Upstash Marketplace integration.
|
|
KV_REST_API_URL="https://<your-upstash-host>.upstash.io"
|
|
KV_REST_API_TOKEN="<your-upstash-rest-token>"
|
|
```
|
|
`JWT_SECRET` is **required** — `lib/auth-secret.js` throws at import time if it's unset.
|
|
|
|
4. **Set up the database**
|
|
```bash
|
|
npm run setup-db
|
|
```
|
|
|
|
5. **Start development server**
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
## 🗄️ Database Schema
|
|
|
|
The application uses the following tables:
|
|
- `users` - User accounts and authentication
|
|
- `cards` - Card information and metadata
|
|
- `user_cards` - User's card collections
|
|
- `collections` - Named card collections
|
|
- `collection_cards` - Cards in collections
|
|
- `decks` - Deck definitions
|
|
- `deck_cards` - Cards in decks
|
|
|
|
## 🔧 API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/auth/register` - User registration
|
|
- `POST /api/auth/login` - User login
|
|
|
|
### Admin
|
|
- `GET /api/admin` - Admin panel data
|
|
|
|
### Health Check
|
|
- `GET /api/health` - Application health
|
|
|
|
> **Note:** Earlier revisions of this README also listed `GET /api/test-db` (and three other unauthenticated dev endpoints: `/api/simple`, `/api/test-auth`, `/api/setup-database`). All four were deleted in `fix-auth-bypass` Brief 3 (commit `fc0dd73`) and CI now blocks their reintroduction. Don't recreate them.
|
|
|
|
## 🚀 Deployment
|
|
|
|
This app is configured for deployment on Vercel:
|
|
|
|
1. **Connect your repository** to Vercel
|
|
2. **Set environment variables** in Vercel dashboard
|
|
3. **Deploy automatically** on push to main branch
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
tcg-vault/
|
|
├── pages/ # Next.js pages and API routes
|
|
│ ├── api/ # API endpoints
|
|
│ │ ├── auth/ # Authentication routes
|
|
│ │ └── admin/ # Admin routes
|
|
│ ├── _app.js # App wrapper
|
|
│ └── index.js # Home page
|
|
├── lib/ # Utility libraries
|
|
│ └── database.js # Database adapter
|
|
├── scripts/ # Database setup scripts
|
|
├── public/ # Static assets
|
|
└── .env.local # Environment variables
|
|
```
|
|
|
|
## 🔐 Default Admin Account
|
|
|
|
After running the database setup:
|
|
- **Email**: admin@tcgvault.com
|
|
- **Password**: admin123
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Submit a pull request
|
|
|
|
## 📄 License
|
|
|
|
MIT License - see LICENSE file for details |