# Platform plan: accounts, billing and admin access

Shared by every paid tool on lebnaus.store. Build this once, then each tool plugs into it.

## Goal

A user signs in once and their access follows them across every subdomain. They buy a plan (monthly, yearly, lifetime, or a bundle) and the matching tools unlock. The owner can set prices and bundles without code changes, and can test everything with admin codes.

## Hosting and stack

- **Hub site:** `accounts.lebnaus.store`, hosted on Namecheap Stellar Plus.
- **Backend:** Node.js app (Express) via cPanel's **Setup Node.js App**. Deploy from the Git repo using the same method as `website`.
- **Database:** MySQL, created in cPanel's **MySQL Databases**. Use a query builder or ORM, not raw string queries.
- **Frontend:** plain HTML, CSS and JavaScript served by the Node app. No build step needed for the hub.
- **Email:** Resend (or SendGrid) for login links and receipts. Verify the domain with DNS records added at Namecheap.
- **Payments:** Stripe (Checkout, Billing and Customer Portal). Test mode first.

Secrets (Stripe keys, webhook secret, email API key, database password, session secret) go in cPanel's Node.js app environment variables. Never in the repo. Add `.env` to `.gitignore`.

## Sessions across subdomains

- The login session is a signed cookie set on the parent domain `.lebnaus.store`, so every subdomain can read it.
- Cookie flags: `HttpOnly`, `Secure`, `SameSite=Lax`. Expire after 30 days, with idle logout.
- Each tool checks access by calling `GET https://accounts.lebnaus.store/api/me`, which returns the user and their entitlements. Tools must never trust their own copy of access rules.

## Data model

- `users`: id, email (unique, lowercased), created_at, is_admin, disabled.
- `login_tokens`: hashed token, user_id, expires_at (15 minutes), used_at. One-time use.
- `sessions`: hashed session id, user_id, created_at, last_seen_at, expires_at.
- `plans`: id, name, description, type (`one_time` or `recurring`), interval (`month`, `year`, or null), stripe_product_id, active.
- `plan_prices`: plan_id, currency (lowercase ISO code: `aud`, `usd`, `eur`, `gbp`, `cad`, `nzd`), amount (cents), stripe_price_id, active. One active row per plan per currency. A price change adds a row and switches the old one off; rows are never edited or deleted.
- `plan_items`: which tools a plan unlocks. A bundle is a plan with several rows here.
- `entitlements`: user_id, tool_key, source (`purchase`, `admin_code`, `admin`), plan_id, starts_at, ends_at (null = lifetime), status (`active`, `cancelled`, `expired`).
- `admin_codes`: id, code_hash, label, tool_keys (or `all`), expires_at, max_uses, uses, revoked.
- `admin_code_redemptions`: code_id, user_id, redeemed_at. One row per person per code.
- `purchases`: stripe_session_id, stripe_customer_id, stripe_subscription_id, user_id, plan_id, plan_price_id (the exact price bought), status, created_at. Used for records and refunds.

## Plans and pricing

- Plans are rows in the database. The owner creates them in the admin page.
- A plan can be priced in several currencies: AUD (the default), USD, EUR, GBP, CAD and NZD. The owner enters a price per currency; a blank currency is not offered.
- Each plan price maps to a Stripe Price. **Stripe Prices can't be edited.** To change a price, create a new Stripe Price and point the plan at it. Old subscribers keep their current price unless you migrate them.
- A plan type is one of: lifetime (one-off), monthly, yearly, or bundle. A bundle is any combination of tools, sold as monthly, yearly or lifetime.

## User flow

1. Visit a tool, e.g. `qr.lebnaus.store`. If the user is free, they can use the free tier.
2. To upgrade, the user is sent to `accounts.lebnaus.store/pricing`, which lists plans from the database.
3. They sign in with an email link. Enter email, get a link, click it, and they're signed in. Links expire after 15 minutes and work once.
4. They choose a currency and a plan. The server creates a Stripe Checkout session with the price looked up on the server by plan and currency, never sent from the browser.
5. Stripe takes payment, then calls our webhook. The webhook is verified with Stripe's signature before any access is granted.
6. The webhook writes entitlements. The user returns to the tool, which now shows the paid features.
7. Subscription users manage billing through the Stripe Customer Portal (cancel, change card, invoices). Cancelling keeps access until the period ends.
8. Lifetime users have no end date.

## Admin access

- **Admin account:** the owner's account has `is_admin = true`. Admins get every tool without paying, and can see the admin page.
- **Admin codes:** the owner can generate a code at any time, as many as needed. Each code has a label, the tools it unlocks (all, or a chosen set), an expiry (1, 7 or 30 days, or a chosen date) and a maximum number of uses (default 1). It is shown once when created, stored as a hash, and never logged.
- Redeeming a code gives access until the code's expiry date, never longer. Each person can redeem a given code once.
- A code can be revoked at any time. Revoking stops new redemptions and removes the access the code gave that is still active.
- Codes are rate-limited on entry (for example 5 tries per IP per 15 minutes) and every redemption is logged.

## Admin page (`accounts.lebnaus.store/admin`)

- Create, edit, activate and deactivate plans. Set the price per currency, interval and included tools.
- Generate admin codes (label, tools, expiry, max uses) and revoke them.
- View users, entitlements, and recent purchases.
- Disable a user.

## Security requirements

- Prices are always looked up server-side, by plan and currency. A currency the plan has no active price for is refused.
- Stripe webhooks are verified using the signing secret. Reject anything that fails.
- Webhook handling is idempotent: the same event processed twice must not double-grant access.
- Login tokens and session ids are random, long, and stored hashed.
- Rate limits on login requests, code entry, and checkout creation.
- CSRF protection on all state-changing requests.
- Set security headers, and never log secrets, card data, or full login tokens.
- Admin routes check `is_admin` on the server for every request.

## Design

- Modern and sleek: clean typography, soft shadows, generous spacing, subtle motion.
- Light and dark modes that follow the device setting, with a toggle.
- Fully responsive: phone (375px and up), tablet, laptop, and large screens. No horizontal scrolling at any width.
- Pricing page with a clear highlight on the recommended plan.
- Accessible: keyboard navigation, visible focus, proper contrast, labelled form fields.

## Acceptance tests

- A new user can sign in with an email link, and the link can't be reused.
- Each plan can be bought in Stripe test mode, and the matching tool unlocks.
- A cancelled subscription keeps access until the end date, then removes it.
- A bundle unlocks every tool it includes.
- An admin code unlocks the chosen tools until it expires, works only up to its use limit, and can be revoked.
- A forged webhook is rejected.
- Changing a plan's price in admin only affects new purchases.
- The pages work at phone, tablet, and laptop widths.

## Open questions for the owner

- Confirm Stripe is available for your country and bank.
- Confirm the email provider (Resend or SendGrid).
- Confirm the currency and starting prices.
- Confirm the admin account email.
