bb05ca731b
Installs the three-layer agent-pipeline scaffold (https://github.com/varutasu/agent-pipeline @ v0.5.0): L1 — Context (curated brain) - AGENTS.md: orientation, conventions, 8 explicit gotchas - .cursor/rules/: no-go-zones, api-routes, auth-and-permissions, db-and-schema, ui-and-theming, schema-map - .cursor/skills/: add-api-route, add-page recipes - docs/agent-context/README.md: layer explainer - docs/SCHEMA_MAP.md: hand-curated Neon Postgres reference (replaces Prisma schema map since stack is raw SQL) L2 — Subagent roles (copied verbatim from upstream templates) - 9 .cursor/agents/role-*.md files: Conductor, IA-Architect, UX-Reviewer, Architect, Implementer, Reviewer, Design-System-Auditor, A11y-Auditor, Doc-Writer L3 — Pipeline scaffolding (Vercel variant) - CI: lint + schema-map-drift only (no duplicate build — Vercel handles it). Test job commented out until vitest lands. - preview-smoke + visual-diff via wait-for-vercel-preview - pr-health-rollup sticky comment aggregator - agent-context-drift weekly cron - PULL_REQUEST_TEMPLATE, CODEOWNERS (auth/admin paths tagged) - .convoys/ folder + seed ship-readiness.md review - lib/flags/index.js (JS — converted from TS template) - scripts/wt.sh (Cursor 3.2 deprecation stub), scripts/log-convoy-event.sh - tests/smoke/app.smoke.spec.ts (Playwright skeleton) Manifest - .agent-context-manifest.yml: tracks 31 artifacts by sha256 for future sync-agent-context drift detection Review - .convoys/ship-readiness.md: 16 findings (7 P0 ship-blockers, 5 P1 quality-bar, 4 P2 refactor, P3 UX/IA/a11y/docs) with proposed 13-convoy launch sequence. No production code changed in this commit. All findings in the ship-readiness review will be addressed in follow-up convoys starting with fix-auth-bypass. Structural brain: user-code-review-graph MCP has indexed the codebase (122 files, 628 nodes, 5602 edges, 11 communities, 84 flows). Per-developer; not committed. Co-authored-by: Cursor <cursoragent@cursor.com>
56 lines
3 KiB
Text
56 lines
3 KiB
Text
---
|
|
description: Auth model + permission model for tcg-vault (JWT + collection roles)
|
|
globs: pages/api/**/*.js,lib/*.js,components/*.js,pages/*.js
|
|
---
|
|
|
|
# Auth + permissions
|
|
|
|
There are three parallel client-side auth implementations and one server-side helper. New code should use the canonical set listed below; don't proliferate variants.
|
|
|
|
## Canonical surface (use these)
|
|
|
|
| Concern | Module |
|
|
| --- | --- |
|
|
| Server: extract user from request | `lib/permission-middleware.js::getUserFromRequest` |
|
|
| Server: gate a collection route | `lib/permission-middleware.js::withCollectionPermission` |
|
|
| Server: log collection mutation | `lib/permission-middleware.js::logCollectionActivity` |
|
|
| Server: token / password primitives | `pages/api/auth-utils.js` (`generateToken`, `verifyToken`, `hashPassword`, `verifyPassword`) |
|
|
| Client: hook | `lib/use-auth.js::useAuth` |
|
|
| Client: route protection | `components/ProtectedRoute.js` |
|
|
| Client: admin route protection | `components/AdminProtected.js` |
|
|
|
|
## Legacy (do not extend)
|
|
|
|
- `lib/auth-context.js::AuthProvider` + `useAuth` — older context. Still wired in `pages/_app.js`; left in place for compatibility. Don't add new consumers.
|
|
- `lib/admin-auth.js::AdminProvider` + `useAdmin` + `useIsAdmin` — parallel admin context. Same story.
|
|
|
|
A convoy is planned to collapse these three into one provider + one hook.
|
|
|
|
## Token model
|
|
|
|
- JWT in localStorage under the key `auth_token`.
|
|
- Signed with `JWT_SECRET` (HS256), 7-day expiry, payload `{ userId, email, role }`.
|
|
- Sent on every authenticated fetch as `Authorization: Bearer <token>`.
|
|
- Verified server-side with `jsonwebtoken.verify(token, JWT_SECRET)`.
|
|
|
|
**JWT_SECRET MUST be set in the deploy environment.** Seven files default it to a string literal if unset; that defeats signing.
|
|
|
|
## Roles
|
|
|
|
Two role surfaces are in play:
|
|
|
|
1. **User role** — `users.role` column, values `'user'` or `'admin'`. Admin gates `/admin/*` pages and admin-only API endpoints.
|
|
2. **Collection role** — `collection_permissions.role` (`viewer` / `editor` / `owner`) + `collections.is_public` (anonymous viewer access). Resolved by `checkCollectionPermission` in priority order: owner → public-viewer → explicit row.
|
|
|
|
When introducing a new permission tier, update both `checkRolePermission`'s hierarchy AND every gate that reads `is_public`.
|
|
|
|
## Authentication state on the client
|
|
|
|
`useAuth()` returns `{ user, loading, login, logout, refresh }`. `user === null` means logged out; `loading === true` means token verification in flight. Always render against `loading === false` before deciding to redirect.
|
|
|
|
## Server-side authorization patterns
|
|
|
|
- **Owner-only** (delete, settings): inside the handler, `if (user.userId !== resource.user_id) return res.status(403)`.
|
|
- **Editor-or-owner**: use `withCollectionPermission('editor')`.
|
|
- **Public read**: use `withCollectionPermission('viewer')` — handles `is_public` and explicit-permission case.
|
|
- **Admin-only**: check `user.role === 'admin'` directly; consider extracting `withAdmin()` if a third call site appears.
|