diff --git a/.planning/STATE.md b/.planning/STATE.md index 1db11f4..c2a4c3f 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -10,28 +10,28 @@ See: .planning/PROJECT.md (updated 2026-03-04) ## Current Position Phase: 1 of 5 (Foundation) -Plan: 2 of 5 in current phase +Plan: 3 of 5 in current phase Status: In progress -Last activity: 2026-03-04 — Completed 01-02-PLAN.md (NextAuth credentials auth, JWT sessions, login UI, middleware) +Last activity: 2026-03-04 — Completed 01-03-PLAN.md (tenant provisioning, Prisma middleware, RLS, isolation tests) -Progress: [██░░░░░░░░] 10% (2/20 plans across all phases) +Progress: [███░░░░░░░] 15% (3/20 plans across all phases) ## Performance Metrics **Velocity:** -- Total plans completed: 2 -- Average duration: 9.5 min -- Total execution time: 19 min +- Total plans completed: 3 +- Average duration: 9.3 min +- Total execution time: 28 min **By Phase:** | Phase | Plans | Total | Avg/Plan | |-------|-------|-------|----------| -| 01-foundation | 2/5 complete | 19 min | 9.5 min | +| 01-foundation | 3/5 complete | 28 min | 9.3 min | **Recent Trend:** -- Last 5 plans: 01-01 (11 min), 01-02 (8 min) -- Trend: accelerating +- Last 5 plans: 01-01 (11 min), 01-02 (8 min), 01-03 (9 min) +- Trend: stable at ~9 min/plan *Updated after each plan completion* @@ -55,6 +55,10 @@ Recent decisions affecting current work: - [01-02]: Super-admin authorize uses OR [isSuperAdmin, tenant.status=ACTIVE] — one Prisma query handles both user types - [01-02]: Seed uses findFirst+create for super-admin (null tenantId) — PostgreSQL NULL != NULL in unique constraints, upsert would create duplicates - [01-02]: SessionProvider wrapped at root layout via Providers component — enables useSession() in all client components +- [01-03]: withTenantContext() creates new $extends per call — correct pattern, $extends is lightweight and request-scoped context is right +- [01-03]: findUnique cross-tenant protection routes through findFirst internally — Prisma unique key cannot have tenantId injected without changing where shape +- [01-03]: RLS USING allows null app.current_tenant_id — super-admin mode (no tenant context) sees all rows +- [01-03]: Initial migration baselined with migrate resolve --applied (schema was created via db push in 01-01) ### Pending Todos @@ -64,10 +68,10 @@ None. - [Phase 1 research flag]: MikroTik RouterOS Node.js client library maintenance status is LOW confidence — verify `node-routeros` vs `mikronode` before implementing router integration (MikroTik integration is v2, but adapter interface should be planned) - [Phase 3 research flag]: Semaphore SMS API pricing/stability for 2026 is MEDIUM confidence — verify before any SMS work (SMS is v2, but abstraction layer design is relevant) -- [01-02 note]: prisma-tenant.ts (from parallel plan 01-03) has TypeScript errors in type checking — auth files are clean. When 01-03 commits, it should fix those errors. +- [01-03 resolved]: prisma-tenant.ts TypeScript errors fixed — Prisma $extends create/upsert required destructuring tenant relation before spreading tenantId ## Session Continuity -Last session: 2026-03-04T10:42:58Z -Stopped at: Completed 01-02-PLAN.md (NextAuth auth + login UI + middleware + seed) +Last session: 2026-03-04T10:45:22Z +Stopped at: Completed 01-03-PLAN.md (tenant provisioning + Prisma middleware + RLS + isolation tests) Resume file: None diff --git a/.planning/phases/01-foundation/01-03-SUMMARY.md b/.planning/phases/01-foundation/01-03-SUMMARY.md new file mode 100644 index 0000000..abd51df --- /dev/null +++ b/.planning/phases/01-foundation/01-03-SUMMARY.md @@ -0,0 +1,155 @@ +--- +phase: 01-foundation +plan: "03" +subsystem: database +tags: [prisma, postgresql, multi-tenancy, rls, bcrypt, next.js, vitest] + +requires: + - phase: 01-01 + provides: Prisma schema with Tenant/User models, singleton PrismaClient, Docker Compose dev environment + +provides: + - Tenant provisioning via POST /api/tenants/signup (creates Tenant + admin User in a transaction) + - Signup UI at /signup with full form validation and redirect to /login?registered=true + - createTenant() service with bcrypt password hashing and unique slug generation + - withTenantContext(tenantId) / createTenantPrisma() — Prisma $extends client for automatic tenant filtering + - setTenantRLS() helper for explicit PostgreSQL RLS enforcement in transactions + - TENANT_SCOPED_MODELS constant for future extensibility + - PostgreSQL RLS policies on User table (defense-in-depth isolation) + - Baseline Prisma migration + RLS migration applied to dev database + - 6 tenant isolation tests proving zero cross-tenant data leakage + +affects: + - 01-04 (plan templates / service plans) — all new models must use withTenantContext() + - 01-05 (dashboard) — tenant context must be threaded from session into prisma-tenant + - All future phases — TENANT_SCOPED_MODELS must be extended as new models are added + +tech-stack: + added: [] + patterns: + - "Prisma $extends query extensions for automatic tenantId injection (not deprecated middleware API)" + - "withTenantContext(tenantId) wraps prisma singleton — one per request, not one per app" + - "RLS as defense-in-depth: Prisma middleware is primary, RLS catches application bugs" + - "Prisma migrate baseline approach for DB first created via db push" + - "EmailAlreadyExistsError custom class for typed 409 vs 400 discrimination in API routes" + +key-files: + created: + - src/lib/tenant.ts + - src/app/api/tenants/signup/route.ts + - src/app/(auth)/signup/page.tsx + - src/lib/prisma-tenant.ts + - src/lib/__tests__/tenant-isolation.test.ts + - prisma/migrations/20260304104214_initial_schema/migration.sql + - prisma/migrations/20260304104245_add_rls_policies/migration.sql + modified: + - prisma/schema.prisma (added businessAddress, contactPhone to Tenant) + - src/app/(auth)/login/page.tsx (added ?registered=true success banner) + +key-decisions: + - "withTenantContext creates a new $extends instance per call — this is intentional; Prisma $extends is lightweight and request-scoped context is correct" + - "findUnique cross-tenant protection routes through findFirst internally — Prisma unique key requires exact match so tenantId cannot be appended naively" + - "RLS USING clause allows null app.current_tenant_id (no context = super-admin mode) — prevents lockout during migrations or admin queries" + - "Initial schema migration baselined (marked applied without running) because schema was created via db push in 01-01" + - "emailInUse check uses findFirst across all non-super-admin users — prevents same email signing up as owner of multiple tenants" + +patterns-established: + - "Tenant filtering pattern: import withTenantContext, call with session.user.tenantId, use returned client for all scoped queries" + - "New tenant-scoped models: add model name to TENANT_SCOPED_MODELS + add model block in $extends in prisma-tenant.ts" + - "Signup → login flow: POST /api/tenants/signup returns 201, client redirects to /login?registered=true" + +duration: 9min +completed: 2026-03-04 +--- + +# Phase 1 Plan 3: Tenant Provisioning and Isolation Summary + +**Tenant signup flow (createTenant + /api/tenants/signup + /signup UI) with Prisma $extends tenant middleware auto-filtering all queries and PostgreSQL RLS policies as defense-in-depth, proven by 6 passing isolation tests.** + +## Performance + +- **Duration:** 9 min +- **Started:** 2026-03-04T10:36:27Z +- **Completed:** 2026-03-04T10:45:22Z +- **Tasks:** 2 completed +- **Files modified:** 9 + +## Accomplishments + +- New ISP tenant signup: POST /api/tenants/signup creates Tenant + admin User atomically via Prisma transaction with bcrypt(12) password hashing and unique slug generation +- Prisma middleware via `$extends` intercepts all 10 query operations (findMany, findFirst, findUnique, create, createMany, update, updateMany, delete, deleteMany, upsert, count, aggregate, groupBy) on tenant-scoped models and automatically injects tenantId +- PostgreSQL RLS policies on User table enabled and applied via migration; setTenantRLS() helper for explicit session-level enforcement +- 6 isolation tests prove zero cross-tenant data leakage: Tenant A queries return zero rows from Tenant B and vice versa; findUnique with wrong tenant returns null + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Tenant signup API, tenant service, and signup UI** - `43761d9` (feat) +2. **Task 2: Prisma tenant middleware, PostgreSQL RLS, and isolation tests** - `69eac9f` (feat) + +## Files Created/Modified + +- `src/lib/tenant.ts` - createTenant() service: validation, slug generation, bcrypt, Prisma transaction +- `src/app/api/tenants/signup/route.ts` - POST /api/tenants/signup: 201/400/409/500 responses +- `src/app/(auth)/signup/page.tsx` - Signup form UI with client-side validation, Tailwind styling +- `src/lib/prisma-tenant.ts` - withTenantContext(), createTenantPrisma(), setTenantRLS(), TENANT_SCOPED_MODELS +- `src/lib/__tests__/tenant-isolation.test.ts` - 6 integration tests proving isolation +- `prisma/migrations/20260304104214_initial_schema/migration.sql` - Baseline migration +- `prisma/migrations/20260304104245_add_rls_policies/migration.sql` - RLS policies on User table +- `prisma/schema.prisma` - Added businessAddress, contactPhone to Tenant model +- `src/app/(auth)/login/page.tsx` - Added registered=true success banner + +## Decisions Made + +- Used Prisma `$extends` with query extensions (not deprecated `$use` middleware API) for forward compatibility with Prisma 6+ +- `findUnique` cross-tenant protection implemented by routing through `findFirst` internally, since Prisma requires exact unique key match which cannot have tenantId appended without changing the where shape +- RLS USING clause permits null `app.current_tenant_id` (no context set = super-admin mode) to prevent migration lockout +- Initial migration baselined with `prisma migrate resolve --applied` since 01-01 used `db push` to initialize schema +- Email uniqueness check before tenant creation queries all non-super-admin users to prevent same email owning multiple tenants + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Fixed TypeScript error in Prisma $extends create/upsert handlers** + +- **Found during:** Task 2 (TypeScript compile check after creating prisma-tenant.ts) +- **Issue:** Spreading `args.data` with `{ ...args.data, tenantId }` included the nested `tenant` relation object, which is mutually exclusive with `tenantId` in Prisma's `UncheckedCreateInput` type +- **Fix:** Destructure out the `tenant` key before spreading: `const { tenant: _t, ...rest } = args.data` then `{ ...rest, tenantId }` +- **Files modified:** src/lib/prisma-tenant.ts +- **Verification:** `npx tsc --noEmit` exits clean, all 6 isolation tests still pass +- **Committed in:** 69eac9f (Task 2 commit) + +**2. [Rule 3 - Blocking] Baselined initial migration before creating RLS migration** + +- **Found during:** Task 2 (running `prisma migrate dev --name add-rls-policies --create-only`) +- **Issue:** Prisma detected schema drift — database was created via `db push` (01-01) so migration history was empty, causing Prisma to require a reset +- **Fix:** Manually created the initial schema migration SQL file and used `prisma migrate resolve --applied` to baseline it, then ran the RLS migration creation cleanly +- **Files modified:** prisma/migrations/20260304104214_initial_schema/migration.sql, prisma/migrations/migration_lock.toml +- **Verification:** `prisma migrate deploy` applied only the RLS migration successfully +- **Committed in:** 69eac9f (Task 2 commit) + +--- + +**Total deviations:** 2 auto-fixed (1 bug, 1 blocking) +**Impact on plan:** Both auto-fixes essential for type safety and migration system correctness. No scope creep. + +## Issues Encountered + +None beyond the auto-fixed deviations above. + +## User Setup Required + +None - no external service configuration required. Database runs in Docker Compose. + +## Next Phase Readiness + +- Tenant provisioning is complete and tested; 01-04 and beyond can assume tenants exist +- All new tenant-scoped Prisma models must be added to `TENANT_SCOPED_MODELS` in src/lib/prisma-tenant.ts AND a query block added to the `$extends` in `withTenantContext()` +- Thread tenant context through session: `withTenantContext(session.user.tenantId)` in Server Components and route handlers +- Plan 01-02 (auth module) runs in parallel — integration between the two is session.user.tenantId flowing into withTenantContext() + +--- +*Phase: 01-foundation* +*Completed: 2026-03-04*