RonanCodes/waitlist-access-control

Waitlist + Access Control

The recurring "not open to the public yet" shape: anyone can ask to get in (waitlist), only approved emails can actually sign in (allowlist), sign-in is passwordless (email OTP), and an admin can approve people and manage roles. This skill wires that end-to-end on the canonical stack (TanStack Start + Better Auth + Drizzle/Postgres + Resend + Cloudflare Workers).

Composes with: /ro:better-auth (the auth base), /ro:resend (email), and the auth-guards canon (server-side route guards). Passwordless choice rationale: see the auth-UX trade-offs (OTP beats passwords for low-friction gated tools; passkeys layer on later).

The model

flowchart TD
    V["Visitor enters email"]:::user
    G{"email in allowlist?"}:::engine
    OTP["send 6-digit OTP (Resend)<br/>→ verify → signed in"]:::out
    WL["upsert waitlist (pending)<br/>+ send waitlist-confirmation email"]:::out
    A["Super-admin whitelists email<br/>→ create user row + allowlist<br/>+ send 'you're in' email"]:::engine
    V --> G
    G -- yes --> OTP
    G -- no --> WL
    WL -.later.-> A
    A -.next sign-in.-> OTP
    classDef user fill:#e0af40,stroke:#b8860b,color:#1a1a1a
    classDef engine fill:#5bbcd6,stroke:#2d7d99,color:#1a1a1a
    classDef out fill:#7dcea0,stroke:#4a9b6e,color:#1a1a1a

Tables (Drizzle, added alongside Better Auth core)

• user.role — column on the existing Better Auth user table: 'super_admin' | 'admin' | 'member', default 'member'.
• allowlist — email (PK, lowercased), role (default 'member'), added_by (user id), created_at. The source of truth for "who may sign in".
• waitlist — email (PK, lowercased), status ('pending' | 'invited'), created_at, notified_at.

Roles

• super_admin — exactly one (or a tiny fixed set), seeded by email. Can do everything, including promote/demote admins. Only a super-admin can grant super-admin; the admin UI never offers it.
• admin — can view users + waitlist, whitelist emails, promote members to admin. Cannot create super-admins.
• member — normal user.

Step 1 — Allowlist-gated passwordless OTP

Use Better Auth's emailOTP plugin with disableSignUp: true (so only pre-created users can sign in), and gate the OTP send on the allowlist. Non-allowlisted emails get waitlisted instead of a code:

// src/lib/auth.ts (inside betterAuth({ ... }))
emailAndPassword: { enabled: false },
plugins: [
  emailOTP({
    otpLength: 6,
    expiresIn: 600,
    disableSignUp: true, // only existing (= whitelisted) users can sign in
    async sendVerificationOTP({ email, otp }) {
      const addr = email.toLowerCase()
      if (await isAllowlisted(addr)) {
        await sendEmail(addr, `Your sign-in code: ${otp}`, otpBody(otp))
      } else {
        await upsertWaitlist(addr)            // status 'pending'
        await sendEmail(addr, `You're on the waitlist`, waitlistBody())
        // do NOT send the OTP — they can't sign in until whitelisted
      }
    },
  }),
],

Double-gate: disableSignUp: true means even a leaked code can't create an account for a non-whitelisted email. Whitelisting an email therefore must create the user row (not just the allowlist row), or first OTP sign-in fails with "no user".

Client: add emailOTPClient() to createAuthClient plugins. Sign-in UI is two steps: email → 6-digit code. If the email wasn't allowlisted, the response is success-but-no-code; show "You're on the waitlist, we'll email you when you're in."

Step 2 — Whitelisting an email (the approve action)

Whitelist = create allowlist row + create the Better Auth user row (random id, name from email, emailVerified: true, role) + flip any waitlist row to invited + send the "you're in" email. Wrap in a server function callable only by admin/super-admin.

async function whitelist(email: string, role: 'member' | 'admin', byUserId: string) {
  const addr = email.toLowerCase()
  await db.insert(allowlist).values({ email: addr, role, addedBy: byUserId }).onConflictDoNothing()
  await db.insert(user).values({ id: randomId(), email: addr, name: addr.split('@')[0], emailVerified: true, role }).onConflictDoNothing()
  await db.update(waitlist).set({ status: 'invited', notifiedAt: new Date() }).where(eq(waitlist.email, addr))
  await sendEmail(addr, `You're in 🎉`, invitedBody(appUrl))
}

Step 3 — Seed the super-admin + initial allowlist

A one-shot seed (script or idempotent migration-time insert) that whitelists the founding emails with roles. Take the super-admin email as a parameter; never hardcode it in shared/engine code (per-app config).

Step 4 — Public waitlist input

A small form (homepage or a /waitlist route) → server fn → upsertWaitlist(email) + confirmation email. Idempotent (re-submitting the same email is a no-op + same friendly message). This is the same waitlist the gate writes to, just a second, explicit entry point.

Step 5 — Three emails (Resend)

1. Waitlist confirmation — "You're on the list, we'll email you when you're in."
2. Whitelisted / you're-in — "You're approved — sign in here" + the app URL.
3. OTP code — "Your sign-in code is NNNNNN" (10-min expiry).

All via Resend from a verified domain. Copy follows /ro:write-copy (no em-dashes, plain, honest).

Step 6 — Admin user-management section

A route group gated by a server-side beforeLoad guard (per auth-guards canon) requiring role in (admin, super_admin):

• Users — table of all users (email, role, created). Promote member→admin (super-admin can also demote / set super-admin; admins cannot grant super-admin — hide/deny it).
• Waitlist — table of pending emails with a one-click Whitelist action (runs Step 2, fires the you're-in email).
• Allowlist — view/remove allowlisted emails.

requireRole('admin') helper on every admin server fn (defence in depth — never trust the client). Super-admin-only actions check role === 'super_admin' explicitly.

Reusable contract / checklist

• [ ] user.role + allowlist + waitlist tables + migration
• [ ] emailOTP + disableSignUp: true, allowlist-gated send
• [ ] whitelist() creates user row + allowlist row + invited email
• [ ] super-admin + founding allowlist seeded (email as param)
• [ ] public waitlist input + confirmation email
• [ ] three Resend emails from a verified domain
• [ ] admin section, server-side role guard, requireRole() on every admin fn
• [ ] super-admin grant is super-admin-only and absent from the admin UI

Related

• /ro:better-auth — the auth base this extends.
• /ro:resend — the email transport (verified domain, send-email server fn).
• auth-guards canon — server-side beforeLoad route guards (every gated route).
• /ro:clerk — the hosted-UI alternative if you'd rather not own the user table.

Provenance

• 2026-06-07 — created from the nutmeg build: Ronan wanted invite-only access (whitelist Eoin + himself), super-admin = himself, an admin user-management section (view users, whitelist, view waitlist, promote admins but not super-admins), and a homepage waitlist input with confirmation + you're-in emails. He flagged it as "a common use case, save it for future." Passwordless OTP chosen over passwords for the gated-tool UX.