Identity, Auth & Access Control

Part of: Pickatale Master Build Wiki | Version: v1.7 | Last Updated: 2026-04-18

14. Lifecycle States

Source: (D) | Status: Confirmed as spec

14.1 Account State

14.2 Subscription State

14.3 Child Account State

14.4 Reading Session State

14.5 Intervention State

15. Identity and Access Flows

→ See Section 28 for full 9-part contracts for all identity flows.

This section is superseded by Section 28 which contains the complete contract format (UI entry point, API endpoints, backend actions, DB writes, events emitted, permission check, entitlement check, audit log, success state, failure paths) for:

• Flow 28.1: Teacher Registration
• Flow 28.2: Email Verification
• Flow 28.3: Teacher / Parent Login
• Flow 28.4: Child Login (Username + PIN)
• Flow 28.5: Logout
• Flow 28.6: Forgot Password
• Flow 28.7: Reset Password
• Flow 28.8: Invite Acceptance
• Flow 28.9: Session Validation Middleware
• Flow 28.10: Session Expiry
• Flow 28.11: Suspended / Disabled Account

16. User Types and Account Ownership

Source: (D) | Status: Confirmed as spec

User Type Definitions

Ownership Rules

• Teacher-created child: students.created_by = teacher_id. The school/teacher owns the account initially. Parent can claim (flow 16.3).
• Parent-created child: OUT OF SCOPE v1 — child accounts created by school/teacher only. students.parent_id is set only via the parent-link flow (see page 11-user-signup-flows).
• Ownership transfer: Teacher can transfer child to parent. Parent cannot transfer child to teacher without teacher action.
• One child, multiple classes: NOT SUPPORTED. Child belongs to exactly one class at a time. Transfer changes class.
• One child, multiple teachers: NOT SUPPORTED. One active teacher per child.
• One parent, multiple children: Supported. Parent has parent_id FK on each child row.
• Teacher license covers all students: teacher's license covers all students in their classes (up to 33 per class).

Child Login: Direct or Parent-Switched?

Decision (spec): Child logs in directly using username + PIN at app.readingtester.com. Parent does NOT switch into child account. Parent has read-only view via parents.readingtester.com using their own login.

Who Can Deactivate a Child?

Parent Claiming a Teacher-Created Child [V1-PRODUCTION]

Flow: Parent registers → in onboarding, enters child's username → system sends verification email to parent → teacher approves claim (or auto-approves if school allows) → students.parent_id = parent.user_id → parent gains read access to child progress.

17. Registration and Onboarding Flows

Source: (D) | Status: Confirmed as spec

17.1 Teacher Onboarding Wizard

Entry: After email verification (flow 15.1) Steps (in order):

1. School Details — school_name, country, year levels taught. Writes to schools or links to existing.
2. Data Processing Agreement — checkbox: "I accept the DPA". Writes users.dpa_accepted_at = now().
3. Create First Class — class_name, year_level. Writes classes row.
4. Import or Add Students — CSV upload (bulk) OR manual add. Creates students rows.
5. Print Login Cards — download PDF. PIN shown here only.
6. First Book Assignment (optional — can skip) — pick from library, assign to class.
7. Done → redirect to Teacher Portal dashboard.

Minimum to proceed: Steps 1–3 required. Steps 4–7 optional but prompted.

17.2 Parent Onboarding Wizard

Entry: After email verification (flow 15.2) Steps (in order):

1. Create Child Profile — child_name, age/birthdate, language, grade_level.
2. Interest Onboarding — select topics child enjoys (animals, space, sport, etc.). Writes students.interest_tags.
3. Subscribe (optional) — show plan options. If skipped → subscription state = none, limited access.
4. Done → redirect to Parent Portal dashboard. Child account is now in state created.

17.3 Child First Login

Entry: Child visits app.readingtester.com, enters username + PIN Steps (in order):

1. Login validated → session created
2. Check students.placement_test_completed:
   • false → Placement Test screen
3. Placement Test: 3 passages at different FK levels. Child reads + answers comprehension questions. System calculates FK level from responses. Writes to students.reading_level and learner_profiles (FK + CEFR). Sets placement_test_completed = true.
4. Interest Picker (if not done by parent): select favourite topics. Writes students.interest_tags.
5. Library → first recommended book displayed in "Picked for You" hero card.

17.4 Class Creation

Entry: Teacher Portal → Classes → New Class

Required fields: class_name (VARCHAR), year_level (INT 1–13) Optional fields: subject, curriculum_territory

Backend actions:

1. Insert classes row: class_name, year_level, teacher_id, school_id, state=active
2. Return class_id

Tables written: classes Emits: no event (internal)

17.5 Student Import (Bulk)

Entry: Teacher Portal → Class → Import Students → Upload CSV

CSV format: name (required), year_level (optional — defaults to class year_level) Backend actions:

1. Parse CSV → validate rows
2. For each row: generate username (firstname + 3-digit number, unique), generate 4-digit PIN, bcrypt PIN, insert students row (state=created, class_id, teacher_id, school_id)
3. Return full list of students with plaintext PINs (shown once only, not stored)

Tables written: students Emails sent: none Output: login cards PDF download

17.6 Learner Profile Initialization

Trigger: Placement test completed (flow 17.3) OR teacher manually sets reading level

Backend actions:

1. POST to Learner Profile Service: learner_id, reading_level (FK), cefr_level
2. POST to Learner Bot: create initial memory records for this learner
3. Set students.placement_test_completed = true

Tables written: learner_profiles (in Learner Profile DB), memories (in Learner Bot DB)

17.7 First Reading Session

Entry: Child at Library → selects book OR clicks "Picked for You"

Steps:

1. Book opened: fires book_opened telemetry event
2. First page_turned event updates reading_sessions.started_at
3. Reading proceeds (words counted, FK-levelled text served)
4. Session ends: fires session_ended → telemetry processes → Learner Bot updated

First session note: No quiz expected after first session. Quiz introduced after 2nd completed book (to avoid friction on first contact).

17.8 First Report Generation

Trigger: Learner Bot nightly cycle (04:00 UTC), minimum 1 completed reading session exists

Output:

• Teacher report: /api/v1/bot/:learner_id/report returns formatted text with curriculum language
• Parent digest: /api/v1/bot/:learner_id/digest returns warm-tone summary

First report contents (minimal): reading level established, first book completed, N words read, vocabulary words tapped.

21. Permissions Matrix

Source: (D) | Status: Confirmed as spec

Entitlement tiers: full = active/trialing/gifted/cancelled-before-end | free = none/expired/past_due-after-grace

28. Identity and Access Flows — Full Contracts

Source: (D) Sig direct instruction | Status: Confirmed as spec. Implementation status per flow noted.

Contract format for every flow:

• UI Entry Point
• API Endpoint(s)
• Backend Actions (in order)
• DB Writes
• Events Emitted
• Permission Check
• Entitlement Check
• Audit Log
• Success State
• Failure Paths

Auth conventions (all flows):

• Cookie: uc_session — httpOnly, SameSite=Lax, domain=.readingtester.com, 7-day rolling expiry
• Child auth: uc_session with role=child, sub=learner_id — same cookie, scoped differently
• JWT in cookie payload: {sub: user_id, role, school_id?, class_id?}
• Password hashing: bcrypt cost 12
• PIN hashing: bcrypt cost 10 (faster, 4-digit)
• Rate limit on all auth endpoints: 5 attempts per 15 min per IP (express-rate-limit)
• All auth events: write to audit_log

Flow 28.1: Teacher Registration

UI Entry Point: account.readingtester.com/register → role selector → "I'm a Teacher"

API Endpoint: POST /api/auth/register

Input:

{
  "name": "string",
  "email": "string",
  "password": "string (min 8, 1 upper, 1 number)",
  "role": "teacher",
  "school_name": "string (optional)"
}

Backend Actions (in order):

1. Validate input (Zod schema). Return 422 if invalid.
2. Query users by email. If exists → 409.
3. bcrypt hash password (cost 12).
4. INSERT users (name, email, password_hash, role='teacher', state='pending_verification', created_at=now()).
5. If school_name provided: INSERT schools (name, country='', admin_user_id=users.id, state='pending'). UPDATE users.school_id.
6. INSERT subscriptions (user_id, state='trialing', tier='trial', trial_ends_at=now()+14d).
7. Generate verification token (UUID v4). INSERT email_verification_tokens (user_id, token_hash=sha256(token), expires_at=now()+48h).
8. POST to SendGrid: template VERIFY_EMAIL (name, verify_url=account.readingtester.com/verify?token=${token}).
9. INSERT email_log (user_id, template='VERIFY_EMAIL', status='sent'|'failed').

DB Writes: users, schools (optional), subscriptions, email_verification_tokens, email_log

Events Emitted: none (no event bus yet; email is the notification)

Permission Check: none (public endpoint)

Entitlement Check: none (pre-auth)

Audit Log: INSERT audit_log (action='register', actor_id=new users.id, metadata={role, email_domain})

Success State: HTTP 201 {ok: true, state: 'pending_verification'}. User redirected to "Check your email" page.

Failure Paths:

Flow 28.2: Email Verification

UI Entry Point: Link in VERIFY_EMAIL email → account.readingtester.com/verify?token=<UUID>

API Endpoint: POST /api/auth/verify-email

Input: { "token": "string" }

Backend Actions:

1. sha256(token) → query email_verification_tokens by token_hash.
2. Check expires_at > now(). If expired → 410.
3. Check already used: used_at IS NULL. If used → 410.
4. UPDATE users.email_verified=true, state='active' WHERE id=token.user_id.
5. UPDATE email_verification_tokens.used_at=now().
6. INSERT sessions (user_id, token_hash=sha256(session_uuid), expires_at=now()+7d, ip, user_agent).
7. Set uc_session cookie.
8. POST to SendGrid: template WELCOME_TEACHER or WELCOME_PARENT (based on role).

DB Writes: users, email_verification_tokens, sessions, email_log

Events Emitted: none

Permission Check: none (public)

Entitlement Check: none

Audit Log: INSERT audit_log (action='email_verified', actor_id=user_id)

Success State: HTTP 200, uc_session set, redirect to /onboarding.

Failure Paths:

Flow 28.3: Teacher / Parent Login

UI Entry Point: account.readingtester.com/login OR teacher.readingtester.com (redirects to account center)

API Endpoint: POST /api/auth/login

Input: { "email": "string", "password": "string" }

Backend Actions:

1. Query users by email. If not found → 401 (identical response — no enumeration).
2. Check users.locked_until. If > now() → 423 with {retry_after: locked_until}.
3. bcrypt.compare(password, password_hash). If false: increment users.failed_attempts. If failed_attempts ≥ 5: set locked_until=now()+15m, send ACCOUNT_LOCKED_ALERT email. Return 401.
4. If valid: reset users.failed_attempts=0, locked_until=null.
5. Check users.state:
   • pending_verification → 403 {error: 'email_not_verified'}
   • suspended → 403 {error: 'account_suspended'}
   • archived → 403 {error: 'account_archived'}
6. INSERT sessions (user_id, token_hash, expires_at=now()+7d, ip, user_agent).
7. Set uc_session cookie.
8. Query subscriptions.state — include in session payload for client-side feature gating hints (server always re-checks).

DB Writes: users (failed_attempts, locked_until), sessions, email_log (if lock email sent)

Events Emitted: none

Permission Check: none (public)

Entitlement Check: none (checked per-request downstream)

Audit Log: INSERT audit_log (action='login', actor_id=user_id, metadata={ip, user_agent, success: true/false})

Success State: HTTP 200, uc_session set, return {ok: true, role, redirect: '/dashboard'}.

Failure Paths:

Flow 28.4: Child Login (Username + PIN)

UI Entry Point: app.readingtester.com → username field + 4-digit PIN

API Endpoint: POST /api/auth/child-login

Input: { "username": "string", "pin": "string (4 digits)" }

Backend Actions:

1. Query students by username (case-insensitive). If not found → 401.
2. Check students.locked=true. If true → 423 {error: 'account_locked', message: 'Ask your teacher to reset your PIN'}.
3. Check students.state. If archived → 403.
4. bcrypt.compare(pin, pin_hash). If false: increment students.failed_attempts. If ≥ 5: students.locked=true. INSERT teacher_notifications (teacher_id, type='child_locked_pin', child_name, student_id). Return 401.
5. If valid: reset students.failed_attempts=0.
6. Call checkEntitlement(students.school_id OR students.parent_id) → determine tier.
7. INSERT sessions (student_id, role='child', learner_id=students.uuid, class_id, expires_at=now()+24h).
8. Set uc_session cookie (role=child, sub=students.uuid, class_id, entitlement_tier).

DB Writes: students (failed_attempts, locked), sessions, teacher_notifications (on lock)

Events Emitted: none

Permission Check: none (public)

Entitlement Check: called to embed tier in session

Audit Log: INSERT audit_log (action='child_login', actor_id=students.uuid, metadata={ip, success})

Success State: HTTP 200, uc_session set. Client checks students.placement_test_completed:

• false → redirect to /placement-test
• true → redirect to /library

Failure Paths:

Flow 28.5: Logout

UI Entry Point: Any page → header "Sign Out" button

API Endpoint: POST /api/auth/logout

Input: none (reads uc_session cookie)

Backend Actions:

1. Parse session_token from uc_session cookie.
2. UPDATE sessions SET invalidated_at=now() WHERE token_hash=sha256(token).
3. Set uc_session cookie with expired date (clear cookie).

DB Writes: sessions

Events Emitted: none

Permission Check: valid uc_session (if none → still clear cookie and redirect)

Entitlement Check: none

Audit Log: INSERT audit_log (action='logout', actor_id=user_id)

Success State: HTTP 200, cookie cleared, redirect to /login.

Failure Paths: Session already invalidated → same outcome (idempotent).

Flow 28.6: Forgot Password

UI Entry Point: /login → "Forgot password?" link → account.readingtester.com/forgot-password

Child exception: Children have no email. Must use teacher PIN reset (Flow 29.7).

API Endpoint: POST /api/auth/forgot-password

Input: { "email": "string" }

Backend Actions:

1. Query users by email. If not found: respond identically (no enumeration).
2. If found: generate token (UUID v4). INSERT password_reset_tokens (user_id, token_hash=sha256(token), expires_at=now()+1h).
3. POST to SendGrid: template PASSWORD_RESET (name, reset_url=account.readingtester.com/reset-password?token=...).
4. INSERT email_log.

DB Writes: password_reset_tokens, email_log

Events Emitted: none

Permission Check: none (public)

Entitlement Check: none

Audit Log: INSERT audit_log (action='forgot_password', metadata={email_domain}) — no user_id (not authenticated)

Success State: HTTP 200 {ok: true}. Client shows "If that email exists, you'll receive a link."

Failure Paths: None user-facing (all paths return 200).

Flow 28.7: Reset Password

UI Entry Point: Link in PASSWORD_RESET email → account.readingtester.com/reset-password?token=<UUID>

API Endpoint: POST /api/auth/reset-password

Input: { "token": "string", "password": "string" }

Backend Actions:

1. sha256(token) → query password_reset_tokens. If not found → 404.
2. Check expires_at > now(). If expired → 410.
3. Check used_at IS NULL. If used → 410.
4. Validate new password strength. If weak → 422.
5. bcrypt hash new password (cost 12).
6. UPDATE users.password_hash, failed_attempts=0, locked_until=null.
7. UPDATE password_reset_tokens.used_at=now().
8. UPDATE sessions SET invalidated_at=now() WHERE user_id=token.user_id (invalidate ALL sessions).
9. POST to SendGrid: template PASSWORD_CHANGED.

DB Writes: users, password_reset_tokens, sessions, email_log

Events Emitted: none

Permission Check: none (token-based)

Entitlement Check: none

Audit Log: INSERT audit_log (action='password_reset', actor_id=user_id)

Success State: HTTP 200. Redirect to /login?message=password_changed.

Failure Paths:

Flow 28.8: Invite Acceptance

UI Entry Point: INVITE_EMAIL link → account.readingtester.com/accept-invite?token=<UUID>

API Endpoint: GET /api/auth/invite?token=<UUID> (prefill form), then POST /api/auth/accept-invite

GET Input: ?token=UUID GET Output: {email: "prefilled@...", role: "teacher", school_name: "...", valid: true}

POST Input:

{
  "token": "string",
  "name": "string",
  "password": "string"
}

Backend Actions (POST):

1. sha256(token) → query invites. If not found → 404.
2. Check expires_at > now(). If expired → 410.
3. Check used_at IS NULL. If used → 410.
4. Check email not already in users. If exists → 409.
5. bcrypt hash password. INSERT users (name, email=invite.target_email, password_hash, role=invite.target_role, school_id=invite.school_id, state='pending_verification').
6. INSERT subscriptions (state='trialing', trial_ends_at=now()+14d) OR inherit school subscription if school_id is set.
7. UPDATE invites.used_at=now().
8. Standard email verification flow (Flow 28.2) triggered automatically.

DB Writes: invites, users, subscriptions, email_verification_tokens, email_log

Events Emitted: none

Permission Check: none (token-based)

Entitlement Check: none

Audit Log: INSERT audit_log (action='invite_accepted', metadata={inviter_id, target_email, role})

Success State: User created, verification email sent, redirect to "Check your email".

Failure Paths:

Flow 28.9: Session Validation (Middleware — Every Protected Request)

Every API endpoint behind auth runs this middleware:

GET /api/auth/session

Steps:

1. Read uc_session cookie.
2. Decrypt/verify JWT. If invalid signature → 401.
3. Query sessions by token_hash. If not found OR invalidated_at IS NOT NULL OR expires_at < now() → 401.
4. Return {user_id, role, school_id, class_id, entitlement_tier}.

On 401: Client clears cookie, redirects to /login?next=<current_path> (child sessions → /login only, no next param).

Flow 28.10: Session Expiry (Automatic)

Trigger: uc_session cookie TTL expires (7 days inactivity) OR server-side invalidation

Client behaviour: Next API call returns 401 → client redirects to login.

Session extension: Every authenticated request: UPDATE sessions.expires_at=now()+7d (sliding window). Children: 24h sliding window.

DB Writes: sessions.expires_at

Flow 28.11: Suspended / Disabled Account

Trigger: Admin sets users.state='suspended'

Immediate effects:

1. UPDATE all sessions.invalidated_at=now() for user (all devices logged out instantly).
2. Send ACCOUNT_SUSPENDED email.

Login attempt while suspended: Flow 28.3 Step 5 → 403 {error: 'account_suspended'}.

Reactivation: Admin sets users.state='active' → INSERT audit_log.

32. Permissions Matrix — Complete [V1-PRODUCTION]

V1 Roles: child, teacher, parent, school_admin, platform_admin

* = also requires age≥8 AND FK≥3.0 † = v1: parent cannot create child accounts — child accounts created by school/teacher flow only ‡ = within same school only