[Future] (optional) Invite-gating enforcement for closed beta

[frankbria]

Parent epic: #174. Decision record: docs/adr/2026-07-04-beta-entitlement-model.md. Deferred from the free-invite beta; out of scope until paid launch is scheduled.

Optional: gate new signups behind an invite/allowlist so the closed beta is actually closed. Would set plan=restricted (the #174 deny path) for non-invited users, or block account creation. Only needed if open signup becomes reachable before paid launch.

AC: non-invited users cannot access AI features (clear upgrade/contact path).

[coderabbitai]

Coding Plan

Summary

• Model entitlement as a first-class plan string on the user record, assigned at creation time from a config-driven email allowlist (INVITE_ONLY_ENABLED + BETA_ALLOWLIST), defaulting to free when gating is off.
• Enforce restriction by cloning the proven get_ai_usage_quota() factory-dependency pattern into a get_entitlement_gate() applied to the same 10 AI endpoints, returning a structured PLAN_RESTRICTED 403 rather than a generic permission error.
• Thread the structured signal through the frontend AI-error layer and present a dedicated upgrade/contact prompt, satisfying the acceptance criterion.
• Ship it disabled-by-default (feature-flagged and bypassed under E2E/auth-bypass), so this optional gate has zero effect until the closed beta actually needs to be closed.

Design Choices

Design Choice 1: Should non-invited users be blocked from creating an account, or allowed to sign up with plan=restricted?

Options Considered:

1. Block account creation entirely at signup — no restricted users ever exist.
2. Allow signup but assign plan=restricted and deny AI features with an upgrade/contact CTA.

Chosen Option: 2

Rationale: The ticket offers both ("set plan=restricted … or block account creation") but the AC requires non-invited users to see a "clear upgrade/contact path," which only makes sense for users who exist in the app. Option 2 directly satisfies the acceptance criterion (restricted users must be able to see an upgrade/contact path inside the product), and reuses the existing per-endpoint gating pattern rather than intercepting better-auth's account creation.

Design Choice 2: How is "invited" determined?

Options Considered:

1. Config-driven email allowlist (BETA_ALLOWLIST) checked at user-creation time — no frontend signup changes required.
2. Invite-code field threaded through the sign-up form → better-auth additionalFields → backend validation.

Chosen Option: 1

Rationale: No invite-code or allowlist infrastructure exists; invite codes are not currently passed through the signup flow. An email allowlist is the smallest change that closes the beta, matches the "allowlist" wording, and avoids touching the better-auth signup contract; invite-code entry can be layered on later if needed.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Entitlement Model & Configuration Foundation

Introduce a first-class plan concept on the user model and the configuration that drives beta gating, so both signup assignment and AI enforcement have a single source of truth. This phase is pure data/config plumbing with no behavior change until later phases consume it.

Task 1: Add a `plan` field to the user models and schemas

Give every user record an explicit entitlement tier defaulting to the open value.

• Add plan: str = "free" to UserBase in backend/app/models/user.py and mirror it in backend/app/schemas/user.py (UserBase/UserResponse/UserInDB), following the existing role: str = "user" precedent.
• Treat plan as a small closed set of string values (free, restricted); document the allowed values in a comment rather than introducing a new enum type unless it reads more clearly.
• Ensure the field surfaces on read responses so the frontend can later reason about entitlement if needed.

Task 2: Add beta-gating configuration flags

Provide feature flags following the existing AI_QUOTA_* idiom so gating can be toggled per environment.

• Add to the Settings class in backend/app/core/config.py: an INVITE_ONLY_ENABLED: bool = False master switch, a BETA_ALLOWLIST of permitted signup emails, and a DEFAULT_RESTRICTED_PLAN/DEFAULT_OPEN_PLAN value pair (or simply reuse "restricted"/"free" constants).
• Parse the allowlist from a comma-separated env var via a @field_validator, mirroring the BACKEND_CORS_ORIGINS pattern; normalize emails to lowercase.
• Keep the existing BYPASS_AUTH short-circuit semantics in mind so gating is disabled under E2E bypass.
• Document the new variables in backend/ENV_VAR_CHANGELOG.md (new dated section, Overview / Added Configuration / Associated Code Changes) and in .env.example.

🤖 Prompt for AI agents

Implement the entitlement data/config foundation with no behavior change yet.

1. In `backend/app/models/user.py`, add `plan: str = "free"` to `UserBase`,
following the existing `role: str = "user"` precedent. Mirror this field in
`backend/app/schemas/user.py` on `UserBase`, `UserResponse`, and `UserInDB`.
Treat `plan` as a closed set of string values (`free`, `restricted`); document
allowed values via a comment rather than introducing a new enum type unless it
reads more clearly. Ensure the field is returned on read responses.

2. In `backend/app/core/config.py`, add to the `Settings` class:
`INVITE_ONLY_ENABLED: bool = False` as a master switch, a `BETA_ALLOWLIST` for
permitted signup emails, and a `DEFAULT_RESTRICTED_PLAN`/`DEFAULT_OPEN_PLAN`
value pair (or reuse `"restricted"`/`"free"` constants directly). Parse the
allowlist from a comma-separated env var using a `@field_validator`, mirroring
the existing `BACKEND_CORS_ORIGINS` pattern, and normalize emails to lowercase.
Ensure the existing `BYPASS_AUTH` short-circuit semantics are respected so
gating can be disabled under E2E bypass.

3. Document the new environment variables in `backend/ENV_VAR_CHANGELOG.md` with
a new dated section (Overview / Added Configuration / Associated Code Changes)
and add them to `.env.example`.

Phase 2: Plan Assignment at User Creation

Assign each new user their entitlement tier at the moment their backend record is created, based on the allowlist. This closes the "who is restricted" question consistently across both creation code paths.

Task 1: Add a shared plan-resolution helper

Centralize the "invited vs restricted" decision so both creation paths behave identically.

• Add a small helper (e.g., in backend/app/core/config.py alongside the settings, or a focused utility module) that, given an email, returns the appropriate plan: when INVITE_ONLY_ENABLED is off return the open plan; when on, return the open plan if the email is in BETA_ALLOWLIST, otherwise restricted.
• Keep the logic pure and side-effect free so it is trivially unit-testable.

Task 2: Apply plan assignment on both user-creation paths

Ensure every newly persisted user gets a plan value regardless of entry point.

• In backend/app/core/security.py, within the auto-create block of get_current_user_from_session, set plan on the user_data dict using the helper before calling create_user (this is the path that fires in production).
• In backend/app/api/endpoints/users.py::create_new_user, add plan to the user_data.update({...}) block alongside role, using the same helper.
• Do not add logic to db/user.py::create_user — keep it a thin insert; the caller supplies plan.

🤖 Prompt for AI agents

Implement plan assignment logic and wire it into both user-creation code paths.

1. Add a small, pure, side-effect-free plan-resolution helper (placed in
`backend/app/core/config.py` alongside the settings, or in a focused utility
module) that takes an email and returns the appropriate plan: when
`INVITE_ONLY_ENABLED` is off, return the open plan; when it is on, return the
open plan if the email is present in `BETA_ALLOWLIST`, otherwise return
`restricted`.

2. Wire the helper into both user-creation paths so every newly persisted user
gets a `plan` value:
- In `backend/app/core/security.py`, inside the auto-create block of
`get_current_user_from_session` (the path that fires in production), set `plan`
on the `user_data` dict using the helper before calling `create_user`.
- In `backend/app/api/endpoints/users.py::create_new_user`, add `plan` to the
`user_data.update({...})` block alongside `role`, using the same helper.

3. Do not add plan-resolution logic to `db/user.py::create_user` — keep it a
thin insert; the caller is responsible for supplying `plan`.

Phase 3: AI Feature Entitlement Enforcement

Deny AI features to restricted users using the established gating pattern, returning a distinguishable, structured signal (not a generic 403) so the frontend can render an upgrade/contact path. This is the core of the acceptance criterion.

Task 1: Add an entitlement error code

Give the restriction a machine-readable identity the frontend can branch on.

• Add a new member (e.g., PLAN_RESTRICTED / INVITE_REQUIRED) to ErrorCode in backend/app/schemas/errors.py.
• Reuse the existing ErrorResponse + create_error_response convention (or the currently-unused AuthorizationErrorResponse) for a consistent structured body.

Task 2: Create the entitlement gate dependency

Add a factory dependency that mirrors get_ai_usage_quota() and blocks restricted plans.

• In backend/app/api/dependencies.py, add get_entitlement_gate() (factory returning an async inner dependency) that declares current_user: Dict = Depends(get_current_user_from_session).
• Short-circuit (return) when settings.BYPASS_AUTH or not settings.INVITE_ONLY_ENABLED, matching the quota gate's bypass-first structure.
• When the resolved user's plan == "restricted", raise HTTPException(status_code=403, detail=<structured body with the new error_code and a clear "contact/upgrade" message>); include an error_code field so the frontend can distinguish it from ordinary permission denials.

Task 3: Wire the gate into all AI endpoints

Apply enforcement uniformly across the AI surface.

• In backend/app/api/endpoints/books.py, add Depends(get_entitlement_gate()) to the dependencies=[...] list of the same 10 AI-consuming route decorators that already carry get_ai_usage_quota() (analyze-summary, generate-questions, generate-toc, chapter generate-questions, regenerate single/all, generate-draft, transform-style, enhance-text, enhance-transcription).

Task 4: Add test fixtures for the gate

Follow the existing fake/real dependency-swap convention so the gate is bypassed by default and testable on demand.

• In backend/tests/conftest.py, add a fake_get_entitlement_gate module-level override plus a real_entitlement_gate fixture, mirroring the existing fake_get_ai_usage_quota / real_ai_quota trio (idempotent stash-the-real / install-the-fake dance).
• Add focused tests asserting: restricted users receive the structured 403 on an AI endpoint; allowlisted/open users are unaffected; plan-resolution helper returns correct values; gate no-ops when disabled or under BYPASS_AUTH.

🤖 Prompt for AI agents

Implement enforcement of the entitlement gate across all AI endpoints, returning
a structured, distinguishable restriction signal.

1. Add a new member (e.g., `PLAN_RESTRICTED` / `INVITE_REQUIRED`) to `ErrorCode`
in `backend/app/schemas/errors.py`. Reuse the existing `ErrorResponse` +
`create_error_response` convention (or the currently-unused
`AuthorizationErrorResponse`) to build a consistent structured error body.

2. In `backend/app/api/dependencies.py`, add a `get_entitlement_gate()` factory
dependency mirroring `get_ai_usage_quota()`: it returns an async inner
dependency that declares `current_user: Dict =
Depends(get_current_user_from_session)`. Short-circuit (`return`) when
`settings.BYPASS_AUTH` or `not settings.INVITE_ONLY_ENABLED`, matching the quota
gate's bypass-first structure. When the resolved user's `plan == "restricted"`,
raise `HTTPException(status_code=403, detail=<structured body>)` including the
new `error_code` and a clear contact/upgrade message, so the frontend can
distinguish it from ordinary permission denials.

3. In `backend/app/api/endpoints/books.py`, add
`Depends(get_entitlement_gate())` to the `dependencies=[...]` list of the same
10 AI-consuming route decorators that already carry `get_ai_usage_quota()`
(analyze-summary, generate-questions, generate-toc, chapter generate-questions,
regenerate single/all, generate-draft, transform-style, enhance-text,
enhance-transcription).

4. In `backend/tests/conftest.py`, add a `fake_get_entitlement_gate`
module-level override plus a `real_entitlement_gate` fixture, mirroring the
existing `fake_get_ai_usage_quota` / `real_ai_quota` trio (idempotent
stash-the-real / install-the-fake pattern). Add focused tests asserting:
restricted users receive the structured 403 on an AI endpoint; allowlisted/open
users are unaffected; the plan-resolution helper returns correct values; and the
gate no-ops when disabled or under `BYPASS_AUTH`.

Phase 4: Frontend Upgrade/Contact Path

Surface the restriction to users with a clear, non-generic message and a contact/upgrade call to action, satisfying the "clear upgrade/contact path" clause of the AC.

Task 1: Preserve the structured restriction signal through the API layer

Make the entitlement error distinguishable downstream instead of collapsing into a generic error.

• Update the aiError() helper in frontend/src/lib/api/bookClient.ts to attach statusCode (as exportError() already does) and preserve the backend error_code, so consumers can branch on plan restriction.
• Add a plan_restricted branch to determineErrorType()/getUserFriendlyMessage() in frontend/src/lib/api/aiErrorHandler.ts (currently 403 falls into unknown).

Task 2: Add an upgrade/contact prompt UI

Render an actionable message when a restricted user attempts an AI feature.

• Create a small presentational component (e.g., UpgradePrompt/ContactUsBanner) under frontend/src/components/ conveying that AI features require an invite/upgrade and providing a contact link/CTA.
• Surface it wherever AI-error states are already rendered (the components consuming generateTocWithErrorHandling, generateQuestionsWithErrorHandling, etc., and/or the shared error notification/toast path) when the new plan_restricted type is detected.
• Keep the generic 403 handling in lib/errors/* intact; only add a distinct branch for the new signal.

🤖 Prompt for AI agents

Implement the frontend surfacing of the entitlement restriction signal with a
dedicated upgrade/contact prompt.

1. Update the `aiError()` helper in `frontend/src/lib/api/bookClient.ts` to
attach `statusCode` (as `exportError()` already does) and preserve the backend
`error_code`, so downstream consumers can branch on plan restriction.

2. Add a `plan_restricted` branch to
`determineErrorType()`/`getUserFriendlyMessage()` in
`frontend/src/lib/api/aiErrorHandler.ts` (currently, a 403 response falls into
the generic `unknown` bucket).

3. Create a small presentational component (e.g.,
`UpgradePrompt`/`ContactUsBanner`) under `frontend/src/components/` that conveys
AI features require an invite/upgrade and provides a contact link/CTA.

4. Surface this component wherever AI-error states are already rendered — the
components consuming `generateTocWithErrorHandling`,
`generateQuestionsWithErrorHandling`, etc., and/or the shared error
notification/toast path — specifically when the new `plan_restricted` type is
detected.

5. Keep the existing generic 403 handling in `lib/errors/*` intact; only add a
distinct branch for the new `plan_restricted` signal.

Research

The backend is a FastAPI app over MongoDB using Pydantic models (backend/app/models/user.py, backend/app/schemas/user.py) with no plan/tier/invite concept today — only a plain role string. Users are mirrored from better-auth into a users collection via two paths: the lazy auto-create block inside get_current_user_from_session (backend/app/core/security.py, the path that actually fires in production) and a currently-unused POST /users endpoint (backend/app/api/endpoints/users.py). All AI features live in backend/app/api/endpoints/books.py (10 endpoints) and are already gated by a factory-style FastAPI dependency get_ai_usage_quota() (backend/app/api/dependencies.py) — the exact template for a new entitlement gate, including its config flags (backend/app/core/config.py) and its fake/real test-swap fixtures (backend/tests/conftest.py). The frontend has no plan/subscription UI; 403s are handled generically as "permission denied" across bookClient.ts, aiErrorHandler.ts, and lib/errors/*. Note: the referenced ADR (docs/adr/2026-07-04-beta-entitlement-model.md) and epic #174 do not exist in this repository; this plan implements the plan=restricted model described in the ticket text.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the entitlement data/config foundation with no behavior change yet.

1. In `backend/app/models/user.py`, add `plan: str = "free"` to `UserBase`,
following the existing `role: str = "user"` precedent. Mirror this field in
`backend/app/schemas/user.py` on `UserBase`, `UserResponse`, and `UserInDB`.
Treat `plan` as a closed set of string values (`free`, `restricted`); document
allowed values via a comment rather than introducing a new enum type unless it
reads more clearly. Ensure the field is returned on read responses.

2. In `backend/app/core/config.py`, add to the `Settings` class:
`INVITE_ONLY_ENABLED: bool = False` as a master switch, a `BETA_ALLOWLIST` for
permitted signup emails, and a `DEFAULT_RESTRICTED_PLAN`/`DEFAULT_OPEN_PLAN`
value pair (or reuse `"restricted"`/`"free"` constants directly). Parse the
allowlist from a comma-separated env var using a `@field_validator`, mirroring
the existing `BACKEND_CORS_ORIGINS` pattern, and normalize emails to lowercase.
Ensure the existing `BYPASS_AUTH` short-circuit semantics are respected so
gating can be disabled under E2E bypass.

3. Document the new environment variables in `backend/ENV_VAR_CHANGELOG.md` with
a new dated section (Overview / Added Configuration / Associated Code Changes)
and add them to `.env.example`.
===============================================================================

Task: 2

Implement plan assignment logic and wire it into both user-creation code paths.

1. Add a small, pure, side-effect-free plan-resolution helper (placed in
`backend/app/core/config.py` alongside the settings, or in a focused utility
module) that takes an email and returns the appropriate plan: when
`INVITE_ONLY_ENABLED` is off, return the open plan; when it is on, return the
open plan if the email is present in `BETA_ALLOWLIST`, otherwise return
`restricted`.

2. Wire the helper into both user-creation paths so every newly persisted user
gets a `plan` value:
- In `backend/app/core/security.py`, inside the auto-create block of
`get_current_user_from_session` (the path that fires in production), set `plan`
on the `user_data` dict using the helper before calling `create_user`.
- In `backend/app/api/endpoints/users.py::create_new_user`, add `plan` to the
`user_data.update({...})` block alongside `role`, using the same helper.

3. Do not add plan-resolution logic to `db/user.py::create_user` — keep it a
thin insert; the caller is responsible for supplying `plan`.
===============================================================================

Task: 3

Implement enforcement of the entitlement gate across all AI endpoints, returning
a structured, distinguishable restriction signal.

1. Add a new member (e.g., `PLAN_RESTRICTED` / `INVITE_REQUIRED`) to `ErrorCode`
in `backend/app/schemas/errors.py`. Reuse the existing `ErrorResponse` +
`create_error_response` convention (or the currently-unused
`AuthorizationErrorResponse`) to build a consistent structured error body.

2. In `backend/app/api/dependencies.py`, add a `get_entitlement_gate()` factory
dependency mirroring `get_ai_usage_quota()`: it returns an async inner
dependency that declares `current_user: Dict =
Depends(get_current_user_from_session)`. Short-circuit (`return`) when
`settings.BYPASS_AUTH` or `not settings.INVITE_ONLY_ENABLED`, matching the quota
gate's bypass-first structure. When the resolved user's `plan == "restricted"`,
raise `HTTPException(status_code=403, detail=<structured body>)` including the
new `error_code` and a clear contact/upgrade message, so the frontend can
distinguish it from ordinary permission denials.

3. In `backend/app/api/endpoints/books.py`, add
`Depends(get_entitlement_gate())` to the `dependencies=[...]` list of the same
10 AI-consuming route decorators that already carry `get_ai_usage_quota()`
(analyze-summary, generate-questions, generate-toc, chapter generate-questions,
regenerate single/all, generate-draft, transform-style, enhance-text,
enhance-transcription).

4. In `backend/tests/conftest.py`, add a `fake_get_entitlement_gate`
module-level override plus a `real_entitlement_gate` fixture, mirroring the
existing `fake_get_ai_usage_quota` / `real_ai_quota` trio (idempotent
stash-the-real / install-the-fake pattern). Add focused tests asserting:
restricted users receive the structured 403 on an AI endpoint; allowlisted/open
users are unaffected; the plan-resolution helper returns correct values; and the
gate no-ops when disabled or under `BYPASS_AUTH`.
===============================================================================

Task: 4

Implement the frontend surfacing of the entitlement restriction signal with a
dedicated upgrade/contact prompt.

1. Update the `aiError()` helper in `frontend/src/lib/api/bookClient.ts` to
attach `statusCode` (as `exportError()` already does) and preserve the backend
`error_code`, so downstream consumers can branch on plan restriction.

2. Add a `plan_restricted` branch to
`determineErrorType()`/`getUserFriendlyMessage()` in
`frontend/src/lib/api/aiErrorHandler.ts` (currently, a 403 response falls into
the generic `unknown` bucket).

3. Create a small presentational component (e.g.,
`UpgradePrompt`/`ContactUsBanner`) under `frontend/src/components/` that conveys
AI features require an invite/upgrade and provides a contact link/CTA.

4. Surface this component wherever AI-error states are already rendered — the
components consuming `generateTocWithErrorHandling`,
`generateQuestionsWithErrorHandling`, etc., and/or the shared error
notification/toast path — specifically when the new `plan_restricted` type is
detected.

5. Keep the existing generic 403 handling in `lib/errors/*` intact; only add a
distinct branch for the new `plan_restricted` signal.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!