Flesh out milestone 5 planning docs

Author: tkxkd0159

docs/SPEC.md

@@ -84,6 +84,7 @@ Non-negotiables:
   - optional expiry
   - optional max uses
 - Current redemption use case is `BETA_SIGNUP`.
+- Generated by the app, not typed in as custom raw values by admins in Milestone 5.
 - Future code purposes can reuse the same domain without changing the public-user auth model.
 
 ### Books
@@ -147,6 +148,10 @@ Admin assigns books to these sections for the club.
 - Internal admins bypass public signup-completion checks, but only for admin routes.
 - Public Google-authenticated users cannot access `/admin/*`.
 - Internal admins should be redirected away from `/signup` and reader-facing product routes.
+- Route behavior defaults:
+  - signed-out access to `/admin/*` redirects to `/admin/signin`
+  - signed-in public-user access to `/admin/*` returns the app’s forbidden experience
+  - signed-in internal-admin access to `/signup`, `/books/*`, `/clubs/*`, `/me/*`, and `/users/*` redirects to `/admin/invitation-codes`
 
 ### Admin Panel
 - Only internal admins can:
@@ -244,6 +249,7 @@ Schema and migration workflow:
   - `providerUserId = normalized email`
   - email/password login
   - manual creation in Supabase UI
+  - no `auth_accounts` row required
 - `nickname` is immutable, unique, lowercase, and URL-safe.
 - `favoriteGenres` is stored as a validated flat list even though the UI groups Fiction and Non-Fiction separately.
 - `invitation_codes` stores:
@@ -255,7 +261,13 @@ Schema and migration workflow:
   - optional `maxUses`
   - `createdById`
 - `invitation_code_redemptions` records each successful code use and supports usage counting and audit history.
+- `maxUses = null` means unlimited use; `expiresAt = null` means no expiry.
+- Invitation-code status shown in the admin UI is derived from:
+  - `isActive`
+  - expiry state
+  - successful redemption count versus `maxUses`
 - Signup code validation and redemption must be transactional so exhausted or inactive codes cannot be raced.
+- Successful signup redemption creates exactly one redemption row and is the only event that increases usage count.
 - Private club invitations target `invitedUserId`; the invite UI resolves nickname to that user on the server.
 - Signup invitation codes and private club invites are separate domains with separate persistence and rules.
 - Personal shelves are independent of clubs by design.
@@ -294,6 +306,7 @@ Store in DB:
 - Internal admins are not created through public signup.
 - Internal admins are created manually in Supabase UI.
 - Internal admin users use `provider = 'internal'`.
+- Internal admin passwords use a bcrypt-compatible hash stored in `users.password_hash`.
 
 ### 7.3 Implementation (Auth.js / NextAuth)
 - Use:
@@ -312,6 +325,12 @@ Store in DB:
   - incomplete public user
   - completed public user
   - internal admin
+- Internal-admin bootstrap should be documented with the exact Supabase fields to populate manually:
+  - `provider`
+  - `provider_user_id`
+  - `email`
+  - `password_hash`
+  - optional `name`
 
 ### 7.4 Auth Rules
 - Public routes:
@@ -335,7 +354,7 @@ Store in DB:
 - `/auth/error` — auth failure state
 - `/signup` — completed-signup onboarding form for authenticated but incomplete public users
 - `/admin/signin` — internal admin sign-in
-- `/admin` — admin landing (can redirect to invitation-code management in Milestone 5)
+- `/admin` — admin landing that redirects to `/admin/invitation-codes` in Milestone 5
 - `/admin/invitation-codes` — internal invitation-code management
 - `/books/search` — search Google Books + add to shelves/clubs
 - `/books/[googleVolumeId]` — book details (from DB or fetched+cached; store book data in our DB after any user searches for it or tries to add it to a club/shelf)
@@ -422,18 +441,19 @@ Admin Invitation Codes (`/admin/invitation-codes`)
 - List codes with:
   - purpose
   - label
-  - active/inactive state
+  - derived status (`ACTIVE`, `INACTIVE`, `EXPIRED`, `EXHAUSTED`)
   - usage count
   - optional expiry
   - optional max uses
   - creator
 - Create new code with:
-  - purpose
+  - purpose (`BETA_SIGNUP` only in Milestone 5 UI)
   - label
   - optional expiry
   - optional max uses
-- Show the raw code once after creation.
+- Generate the raw code server-side and show it once after creation.
 - Allow activation/deactivation.
+- Do not support editing the raw code, expiry, or max uses after creation in Milestone 5.
 - Show redemption history or usage details sufficient to explain exhausted or inactive state.
 
 Club Home (`/clubs/[clubId]`)
@@ -542,15 +562,17 @@ Navigation
   - required at signup completion
   - must match an active `BETA_SIGNUP` code
   - must respect expiry and max-uses rules when those are configured
+  - successful redemption is counted only once per user
 - Internal admin sign-in:
   - valid email required
   - password required
-  - credentials verified against stored password hash
+  - credentials verified against stored bcrypt-compatible password hash
 - Invitation code creation:
   - `purpose` required
   - `label` required
   - `expiresAt` optional and, if present, must be a future timestamp
   - `maxUses` optional and, if present, must be a positive integer
+  - raw code value is generated by the server
 - Club name: 2–60 chars
 - Thread title: 2–120 chars
 - Post body: 1–10,000 chars
@@ -592,6 +614,7 @@ Navigation
   - for shelves, always resolve ownership internally by userId after nickname lookup
 - Provider email must not be used as the authoritative public identity for authorization or invite acceptance.
 - Public users cannot access `/admin/*`, and internal admins cannot use the public onboarding path.
+- Deactivating or expiring an invitation code does not revoke access for users who already redeemed it successfully.
 
 ## 13) MVP Milestones
 
@@ -685,8 +708,17 @@ Use `sortOrder`:
 - Internal admins use:
   - `provider = 'internal'`
   - `providerUserId = normalized email`
-  - password-hash verification
+  - bcrypt-compatible password-hash verification
+- Manual Supabase bootstrap should populate:
+  - `provider`
+  - `provider_user_id`
+  - `email`
+  - `password_hash`
+  - optional `name`
+- Internal admin bootstrap does not require inserting an `auth_accounts` row.
 - Internal admins do not use public signup or public product routes in Milestone 5.
 - Invitation codes are modeled for future reuse through `purpose`, optional expiry, and optional max uses, but only `BETA_SIGNUP` is redeemed in Milestone 5.
-- Raw invitation codes are shown once at creation and then only the hash remains persisted.
+- Raw invitation codes are system-generated, shown once at creation, and then only the hash remains persisted.
+- `maxUses = null` means unlimited use; `expiresAt = null` means no expiry.
+- Admins can activate/deactivate codes, but editing code body, expiry, or max uses after creation is out of scope in Milestone 5.
 - Milestone 5 private club invites can only target existing signed-up public users with a nickname.

docs/tasks/milestone-5/milestone-5-beta-onboarding-admin-auth-and-invitation-codes.md

@@ -22,9 +22,12 @@ Deliver the closed-beta onboarding and service-native identity workflow on top o
 - Internal admins are manually created in Supabase UI and stored with `provider = 'internal'`.
 - Internal admins use email/password only and do not participate in public signup or the public product routes.
 - Invitation codes are future-ready through `purpose`, optional expiry, and optional max uses, but only `BETA_SIGNUP` redemption is implemented in Milestone 5.
+- Invitation codes are system-generated by the app and shown in raw form only once at creation time; admins do not type custom raw code values in Milestone 5.
+- Invitation-code status in the admin UI is derived from `isActive`, `expiresAt`, and successful redemption count so admins can distinguish active, inactive, expired, and exhausted codes.
 - Nickname is immutable in Milestone 5 and is validated as a lowercase URL-safe handle.
 - Private club invites remain a separate domain from admin-managed invitation codes.
 - Milestone 5 does not add a public profile route, nickname change UI, or in-app admin-user bootstrap flow.
+- Signed-in public users who try to access `/admin/*` should see a forbidden experience, while internal admins who try to enter `/signup` or reader-app routes should be redirected back to `/admin/invitation-codes`.
 
 ## Delivery Order
 1. [Task 01: User and Admin Identity Foundation](./task-01-user-and-admin-identity-foundation.md)
@@ -38,6 +41,7 @@ Deliver the closed-beta onboarding and service-native identity workflow on top o
 - Completing signup persists nickname, gender, country, favorite genres, and signup completion state, and atomically redeems a valid `BETA_SIGNUP` invitation code.
 - Internal admins can sign in through `/admin/signin` and manage invitation codes from `/admin/invitation-codes`.
 - Invitation codes are stored hashed, support active/inactive state, and can optionally expire or cap uses.
+- Manual Supabase bootstrap requirements for internal admins are documented clearly enough that an operator can create an internal admin without app-side seeding.
 - Nickname becomes the default user-facing identity across `/me`, shelves, clubs, threads, reviews, and invite pages.
 - Public shelf sharing works by nickname route while preserving the existing signed-in-only public shelf access model.
 - Private club invites are created by nickname and accepted only by the targeted signed-in public user.

docs/tasks/milestone-5/task-01-user-and-admin-identity-foundation.md

@@ -28,6 +28,11 @@ Add the schema, shared validation, repository contracts, and identity helpers ne
   - `InvitationCodeRecord`
   - `InvitationCodeRedemptionRecord`
   - public user vs internal admin session identity
+- Define shared status helpers for invitation-code lifecycle evaluation:
+  - active
+  - inactive
+  - expired
+  - exhausted
 - Update auth and user repository contracts so app identity no longer depends on provider email for normal signed-in flows.
 
 ## Implementation Notes
@@ -36,22 +41,33 @@ Add the schema, shared validation, repository contracts, and identity helpers ne
 - Internal admins are represented by:
   - `provider = 'internal'`
   - `provider_user_id = normalized email`
-  - password-hash verification
+  - bcrypt-compatible password-hash verification
 - Internal admins are manually created in Supabase UI and are not provisioned by the app.
 - OAuth-linked public users still use `auth_accounts`; internal credentials auth can resolve directly from `users`.
+- Internal admin records should not require `auth_accounts` rows in Milestone 5.
+- This task should document the exact manual Supabase bootstrap fields for internal admins:
+  - `provider`
+  - `provider_user_id`
+  - `email`
+  - `password_hash`
+  - optional `name`
 - Invitation codes must be stored hashed and modeled for future purposes even though only `BETA_SIGNUP` is redeemed in this milestone.
+- `maxUses = null` means unlimited use; `expiresAt = null` means no expiry.
+- Successful redemption count is derived from `invitation_code_redemptions`; failed validation attempts do not create redemption rows.
 
 ## Acceptance Criteria
 - The database schema and app-facing types expose all required Milestone 5 public-user, internal-admin, and invitation-code fields.
 - Shared validation covers nickname normalization, allowed genre values, required country/gender selection, internal admin auth inputs, and invitation-code hashing contracts.
 - Reusable repository helpers can distinguish incomplete public users, completed public users, and internal admins without route-local duplication.
 - Shared display helpers make nickname the first-class reader-facing identity.
 - Shared code-management types are stable enough to support future invitation-code purposes without revisiting the schema shape.
+- Manual internal-admin bootstrap requirements are explicit enough that implementation does not need a second design pass for Supabase setup.
 
 ## Expected Touchpoints
 - `db/schema/data.sql`
 - `db/migrations/*`
 - `types/db/index.ts`
 - `lib/auth/*`
+- `lib/invitation-codes/*`
 - `tests/unit/auth*.test.ts`
 - invitation-code validation and repository helpers

docs/tasks/milestone-5/task-02-signup-completion-and-public-app-auth-gating.md

@@ -19,6 +19,7 @@ Implement the completed-signup flow so authenticated but incomplete public users
   - direct protected-page hits by incomplete public users
 - Redirect incomplete public users away from reader-facing protected routes and protected mutations until `signup_completed_at` is set.
 - Redirect completed public users away from `/signup` to the callback destination or `/books/search`.
+- Ensure internal admins never enter the public signup flow and are redirected to `/admin/invitation-codes` instead.
 
 ## Implementation Notes
 - Keep Google OAuth as the only public-user provider for Milestone 5, but treat OAuth and completed signup as separate lifecycle steps.
@@ -28,13 +29,15 @@ Implement the completed-signup flow so authenticated but incomplete public users
 - Invite links and other protected deep links should survive the onboarding detour by preserving callback intent.
 - Sign-out remains available to incomplete public users.
 - Invitation-code redemption should record audit history and enforce inactive, expired, exhausted, and wrong-purpose rejections on the server.
+- A successful signup redemption should consume one available use exactly once, even under concurrent submission attempts.
 
 ## Acceptance Criteria
 - A newly authenticated but incomplete public user is redirected to `/signup` before any reader-facing app surface renders.
 - Completing signup writes the required profile fields, marks signup complete, redeems the code, and redirects the user back to the intended destination.
 - Protected reader-facing server actions reject incomplete public users consistently.
 - Completed public users cannot accidentally return to `/signup` as a normal app page.
 - Invalid, inactive, expired, exhausted, and wrong-purpose invitation codes are rejected with clear server-enforced behavior.
+- Internal admins cannot complete public signup and are redirected back to the admin panel instead.
 
 ## Expected Touchpoints
 - `app/signup/page.tsx`
@@ -43,4 +46,5 @@ Implement the completed-signup flow so authenticated but incomplete public users
 - `app/api/auth/[...nextauth]/route.ts`
 - `proxy.ts`
 - `lib/auth/server.ts`
+- signup-completion repository helpers and tests
 - signup-completion server actions and tests

docs/tasks/milestone-5/task-03-internal-admin-auth-and-invitation-code-management.md

@@ -5,11 +5,12 @@ Add the internal-only auth path and admin surface needed to manage invitation co
 
 ## Scope
 - Add `/admin/signin` for internal admin email/password login.
+- Add `/admin` as a lightweight landing route that redirects to `/admin/invitation-codes`.
 - Configure Auth.js Credentials auth for internal users stored with `provider = 'internal'`.
 - Add internal-only route protection for `/admin/*`.
 - Add `/admin/invitation-codes` with the required Milestone 5 flows:
   - list codes with purpose, label, status, usage count, expiry, max uses, and creator
-  - create a code with purpose, label, optional expiry, and optional max uses
+  - create a system-generated code with purpose, label, optional expiry, and optional max uses
   - activate/deactivate a code
   - show usage details or redemption history sufficient to explain inactive or exhausted state
 - Show the raw invitation code only once at creation time while persisting only the hash.
@@ -21,18 +22,26 @@ Add the internal-only auth path and admin surface needed to manage invitation co
 - Internal users should land on `/admin/invitation-codes` after successful sign-in.
 - Invitation-code management is future-ready through `purpose`, optional expiry, and optional max uses, but only `BETA_SIGNUP` redemption is implemented in Milestone 5.
 - The admin route contract can stay compact; usage details may be inline on `/admin/invitation-codes` instead of requiring a second admin detail route.
+- In Milestone 5, code creation UI can expose `purpose` as a fixed single-option control or a read-only value so implementation does not need a multi-purpose admin UX yet.
+- Admins can activate/deactivate codes, but editing a code’s raw value, expiry, or max uses after creation is out of scope in Milestone 5.
+- The list surface should show derived status, not just raw `isActive`, so exhausted and expired codes are immediately understandable.
 
 ## Acceptance Criteria
 - Internal admins can authenticate successfully with email/password through `/admin/signin`.
 - Invalid credentials fail cleanly without creating or mutating users.
 - `/admin/invitation-codes` lets internal admins create, activate/deactivate, and inspect codes and usage data.
 - Raw codes are only shown at creation time and are not persisted in plaintext.
 - Public users are blocked from `/admin/*`, and internal admins are redirected away from `/signup`.
+- Manual internal-admin bootstrap is documented with enough field-level detail to be reproducible through Supabase UI.
 
 ## Expected Touchpoints
 - `app/admin/signin/page.tsx`
+- `app/admin/page.tsx`
+- `app/admin/layout.tsx`
 - `app/admin/invitation-codes/page.tsx`
 - `app/api/auth/[...nextauth]/route.ts`
+- `components/admin/*`
 - `proxy.ts`
 - `lib/auth/*`
+- `lib/invitation-codes/*`
 - invitation-code repositories, server actions, and tests

docs/tasks/milestone-5/task-04-nickname-profile-public-shelf-sharing-and-club-invites.md

@@ -29,6 +29,7 @@ Make nickname the default reader-facing identity, switch public shelf sharing fr
 - Invitation codes and private club invites are separate domains and should not be coupled in repository or UI behavior.
 - Inviting someone who has not completed signup is out of scope; the club-invite flow should fail clearly when the nickname does not map to a signed-up public user.
 - Duplicate pending club invites should be blocked per `clubId + invitedUserId`.
+- Invite acceptance UI and copy should stop referring to email entirely and should identify the invite target by nickname or a generic targeted-user message.
 
 ## Acceptance Criteria
 - `/me` clearly shows nickname as the primary Book by Book identity and surfaces the new profile fields.
@@ -37,6 +38,7 @@ Make nickname the default reader-facing identity, switch public shelf sharing fr
 - Club admins create private invites by nickname, not email.
 - Private-club invite creation fails with a clear error when the nickname does not exist, is incomplete, or already belongs to a club member.
 - Accepting a valid private-club invite works only for the targeted signed-in public user and remains idempotent.
+- Reader-facing invite pages and member/profile surfaces no longer rely on provider email as the visible identity fallback when nickname exists.
 
 ## Expected Touchpoints
 - `app/(protected)/me/page.tsx`