@xk2800/nextjs-template 0.7.1-beta.1 → 0.7.1-beta.11

package/README.md

@@ -33,25 +33,25 @@ UPDATE "user" SET roles = 'admin' WHERE email = 'you@example.com';
 ## Features
 
 - **Auth:** email/password, Google OAuth, Google One Tap, passkeys, TOTP 2FA with backup codes, password reset, email verification
-- **Security:** new-device email alerts, per-device sign-in/sign-up throttle, active-session revocation, self-serve account deletion, cookie-consent banner
-- **Admin:** user management (roles, bans, bulk actions, CSV export), impersonation, system-wide activity log, device-security cards, live auth toggles, maintenance mode
+- **Security:** new-device email alerts, per-device sign-in/sign-up throttle, active-session revocation, self-serve account deletion, cookie-consent banner with an admin consent-mode switch
+- **Admin:** user management (roles, bans, bulk actions, CSV export), impersonation, system-wide activity log, device-security cards, live auth toggles, maintenance mode, marketing email via Resend Broadcasts with user self opt-in (Beta)
 - **Ops:** `bun run doctor`, Docker image, Doppler support, separate env files for dev, prod and test
 
 ## Docs
 
-| Topic | |
-|---|---|
-| Every env var, env vs. admin settings, Doppler | [Configuration](docs/content/configuration.mdx) |
-| Folder layout, request flow, adding protected pages/routes | [Architecture](docs/content/architecture.mdx) |
-| Tables, column gotchas, migrations | [Database](docs/content/database.mdx) |
-| Providers, sessions, helpers, client usage | [Authentication](docs/content/authentication.mdx) |
-| 2FA, passkeys, device alerts, throttle, cookie consent | [Security Features](docs/content/security.mdx) |
-| Admin dashboard, impersonation, maintenance mode | [Admin & Maintenance](docs/content/admin.mdx) |
-| Every route, body and guard | [API Reference](docs/content/api.mdx) |
-| UI, auth, dashboard and email components | [Components](docs/content/components.mdx) |
-| Installing the npm package | [Using as a Package](docs/content/npm-package.mdx) |
-| Production checklist, migrations, Docker | [Deployment](docs/content/deployment.mdx) |
-| Common errors and fixes | [Troubleshooting](docs/content/troubleshooting.mdx) |
+| Topic                                                      |                                                     |
+| ---------------------------------------------------------- | --------------------------------------------------- |
+| Every env var, env vs. admin settings, Doppler             | [Configuration](docs/content/configuration.mdx)     |
+| Folder layout, request flow, adding protected pages/routes | [Architecture](docs/content/architecture.mdx)       |
+| Tables, column gotchas, migrations                         | [Database](docs/content/database.mdx)               |
+| Providers, sessions, helpers, client usage                 | [Authentication](docs/content/authentication.mdx)   |
+| 2FA, passkeys, device alerts, throttle, cookie consent     | [Security Features](docs/content/security.mdx)      |
+| Admin dashboard, impersonation, maintenance mode           | [Admin & Maintenance](docs/content/admin.mdx)       |
+| Every route, body and guard                                | [API Reference](docs/content/api.mdx)               |
+| UI, auth, dashboard and email components                   | [Components](docs/content/components.mdx)           |
+| Installing the npm package                                 | [Using as a Package](docs/content/npm-package.mdx)  |
+| Production checklist, migrations, Docker                   | [Deployment](docs/content/deployment.mdx)           |
+| Common errors and fixes                                    | [Troubleshooting](docs/content/troubleshooting.mdx) |
 
 ## Using as a package
 
@@ -63,7 +63,7 @@ bun add @xk2800/nextjs-template
 
 ```ts
 // next.config.ts — components ship as raw .tsx
-const nextConfig = { transpilePackages: ["@xk2800/nextjs-template"] }
+const nextConfig = { transpilePackages: ["@xk2800/nextjs-template"] };
 ```
 
 ```css
@@ -75,25 +75,27 @@ const nextConfig = { transpilePackages: ["@xk2800/nextjs-template"] }
 
 ```ts
 // app/api/auth/[...all]/route.ts
-import { auth } from "@xk2800/nextjs-template/auth"
-import { toNextJsHandler } from "better-auth/next-js"
-export const { GET, POST } = toNextJsHandler(auth)
+import { auth } from "@xk2800/nextjs-template/auth";
+import { toNextJsHandler } from "better-auth/next-js";
+export const { GET, POST } = toNextJsHandler(auth);
 ```
 
 Peer dependencies, the full import list, migrations, adding providers and One Tap are covered in **[Using as a Package](docs/content/npm-package.mdx)**.
 
 ## Common scripts
 
-| | |
-|---|---|
-| `bun dev` | Dev server |
-| `bun run doctor` | Check env, auth secret, DB connection and pending migrations |
-| `bun update @xk2800/nextjs-template` | Pull template updates (then `bun run generate`) |
-| `bun run generate` | Generate a migration from `server/db/schema.ts` |
-| `bun run migrate:dev` / `:prod` / `:test` | Apply migrations |
-| `bun run studio:dev` | Drizzle Studio |
-| `bun run test` | Unit tests |
-| `bun run storybook` | Storybook for every component (mock data, no DB needed) |
-| `bun run *:doppler` | Any of the above with secrets from Doppler |
+|                                           |                                                              |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `bun dev`                                 | Dev server                                                   |
+| `bun run doctor`                          | Check env, auth secret, DB connection and pending migrations |
+| `bun update @xk2800/nextjs-template`      | Pull template updates (then `bun run generate`)              |
+| `bun run generate`                        | Generate a migration from `server/db/schema.ts`              |
+| `bun run migrate:dev` / `:prod` / `:test` | Apply migrations                                             |
+| `bun run studio:dev`                      | Drizzle Studio                                               |
+| `bun run test`                            | Unit tests                                                   |
+| `bun run storybook`                       | Storybook for every component (mock data, no DB needed)      |
+| `bun run *:doppler`                       | Any of the above with secrets from Doppler                   |
 
 **Working on the template itself:** clone this repo, copy `.env.development.example` to `.env.development`, then run `bun install`. Publishing steps are in [PUBLISHING.md](PUBLISHING.md).
+
+test

package/components/auth/deviceCheck.tsx

@@ -2,8 +2,8 @@
 
 import { useEffect } from 'react'
 import { useSession } from '../../lib/auth-client'
-import { getVisitorId } from '../../lib/device-fingerprint'
-import { useCookieConsent } from '../../lib/cookie-consent'
+import { clearStoredVisitorId, getDeviceSignals, getStoredVisitorId, getVisitorId } from '../../lib/device-fingerprint'
+import { useConsentFor, useCookieConsent } from '../../lib/cookie-consent'
 
 // Mount once (e.g. in the root layout). When a session is present it computes
 // a FingerprintJS device id and hands it to /api/device-check, which emails
@@ -13,15 +13,51 @@ import { useCookieConsent } from '../../lib/cookie-consent'
 // email/password, Google OAuth and One Tap without touching any of them. The
 // endpoint is idempotent — the alert only fires on the first ever POST for a
 // given (user, device).
+//
+// Also handles withdrawn consent: once the visitor's choice no longer
+// includes the "fingerprint" purpose ("Necessary only", or unticked under
+// "Customize"), the stored device id is sent to DELETE /api/device-check so this device's
+// record is erased, then forgotten. Withdrawn while signed out ⇒ it happens on
+// the next sign-in.
+// ponytail: erases only the signed-in account's row for this device. The id
+// is forgotten after that, so other accounts that used this browser keep
+// their rows until those accounts are deleted (deliberate: one person's
+// choice shouldn't erase other accounts' security records).
 export default function DeviceCheck() {
   const { data: session } = useSession()
   const userId = session?.user?.id
   // The fingerprint needs optional-cookie consent (lib/device-fingerprint.ts);
   // re-run when it's granted so the check doesn't wait for the next page load.
   const consent = useCookieConsent()
+  const fingerprintAllowed = useConsentFor('fingerprint')
 
   useEffect(() => {
-    if (!userId || consent !== 'all') return
+    if (!userId) return
+
+    // A choice was made (consent !== null) and it excludes the fingerprint.
+    if (consent !== null && !fingerprintAllowed) {
+      // Re-consenting later in this tab must POST again — the row is gone.
+      try {
+        sessionStorage.removeItem('device-checked')
+      } catch {
+        // ignore
+      }
+      const visitorId = getStoredVisitorId()
+      if (!visitorId) return
+      fetch('/api/device-check', {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ visitorId }),
+      })
+        .then((res) => {
+          // Keep the id on failure so the next page load retries the erasure.
+          if (res.ok) clearStoredVisitorId()
+        })
+        .catch(() => {})
+      return
+    }
+
+    if (!fingerprintAllowed) return
 
     const run = async () => {
       try {
@@ -34,11 +70,16 @@ export default function DeviceCheck() {
       const visitorId = await getVisitorId()
       if (!visitorId) return
 
-      await fetch('/api/device-check', {
+      const res = await fetch('/api/device-check', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ visitorId }),
+        // components: the device's signals for the admin user page.
+        body: JSON.stringify({ visitorId, components: await getDeviceSignals() }),
       })
+      // Only a success counts as checked — a failed request (server error,
+      // deploy in progress) must retry on the next page load, not wait for
+      // a new browser session.
+      if (!res.ok) return
 
       try {
         sessionStorage.setItem('device-checked', userId)
@@ -50,7 +91,7 @@ export default function DeviceCheck() {
     // Best-effort: fingerprinting or the network failing must never surface
     // to the user mid-app.
     run().catch(() => {})
-  }, [userId, consent])
+  }, [userId, consent, fingerprintAllowed])
 
   return null
 }

package/components/auth/oneTap.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import { authClient, useSession } from '../../lib/auth-client'
-import { useCookieConsent } from '../../lib/cookie-consent'
+import { useConsentFor } from '../../lib/cookie-consent'
 import { useRouter } from 'next/navigation'
 import React, { useEffect, useState } from 'react'
 
@@ -22,8 +22,8 @@ const OneTap = ({ callbackURL = '/dashboard' }: OneTapProps) => {
   // never fire the prompt before we've actually heard back.
   const [oneTapOffered, setOneTapOffered] = useState<boolean | null>(null)
   // Google's One Tap script is third-party and can use Google's cookies, so
-  // it only loads once the visitor accepts optional cookies.
-  const consent = useCookieConsent()
+  // it only loads once the visitor consents to the "onetap" purpose.
+  const oneTapAllowed = useConsentFor('onetap')
 
   useEffect(() => {
     if (process.env.NEXT_PUBLIC_AUTH_ENABLE_ONE_TAP !== 'true') return
@@ -39,7 +39,7 @@ const OneTap = ({ callbackURL = '/dashboard' }: OneTapProps) => {
     if (process.env.NEXT_PUBLIC_AUTH_ENABLE_ONE_TAP !== 'true') return
     if (isPending || session) return
     if (oneTapOffered !== true) return
-    if (consent !== 'all') return
+    if (!oneTapAllowed) return
 
     authClient.oneTap({
       callbackURL,
@@ -47,7 +47,7 @@ const OneTap = ({ callbackURL = '/dashboard' }: OneTapProps) => {
         console.log('One Tap prompt notification:', notification)
       }
     })
-  }, [session, isPending, callbackURL, oneTapOffered, consent])
+  }, [session, isPending, callbackURL, oneTapOffered, oneTapAllowed])
 
   return null
 }

package/components/dashboard/admin/adminUserConsentCard.tsx

@@ -0,0 +1,79 @@
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "../../ui/card"
+import { Badge } from "../../ui/badge"
+import { CONSENT_PURPOSES, consentAllows, type ConsentPurpose } from "../../../lib/cookie-names"
+import { formatDateTime } from "../../../lib/formatters"
+
+interface ConsentRecord {
+  id: string
+  choice: string
+  version: number
+  createdAt: Date
+}
+
+const PURPOSE_LABELS: Record<ConsentPurpose, string> = {
+  fingerprint: "Security fingerprint",
+  onetap: "Google One Tap",
+}
+
+function describeChoice(choice: string): string {
+  if (choice === "all") return "Accepted all"
+  if (choice === "necessary") return "Necessary only"
+  return "Custom"
+}
+
+// The user's cookie-consent records (consent_log, proof of consent under GDPR
+// Art. 7(1)): the current choice per purpose, then every change with the
+// consent-text version it was given under.
+export default function AdminUserConsentCard({
+  records,
+  consentRequired,
+}: {
+  records: ConsentRecord[]
+  consentRequired: boolean
+}) {
+  const current = records[0]
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Consent</CardTitle>
+        <CardDescription>
+          Cookie choices this user made while signed in, kept as proof of consent
+          {!consentRequired && ". Consent isn't currently required, so new choices aren't being recorded"}
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        {!current ? (
+          <p className="text-center text-gray-500 py-8">No consent recorded</p>
+        ) : (
+          <div className="space-y-4">
+            <div className="flex flex-wrap gap-2">
+              {CONSENT_PURPOSES.map((purpose) => {
+                const allowed = consentAllows(current.choice, purpose)
+                return (
+                  <Badge key={purpose} variant={allowed ? "default" : "outline"}>
+                    {PURPOSE_LABELS[purpose]}: {allowed ? "allowed" : "declined"}
+                  </Badge>
+                )
+              })}
+            </div>
+            <ul className="divide-y divide-border rounded-md border border-border text-sm">
+              {records.map((r, i) => (
+                <li key={r.id} className="flex flex-wrap items-center justify-between gap-2 px-4 py-2">
+                  <span>
+                    <span className="font-medium">{describeChoice(r.choice)}</span>
+                    <span className="ml-2 font-mono text-xs text-gray-500">{r.choice}</span>
+                    {i === 0 && <span className="ml-2 text-xs text-gray-500">(current)</span>}
+                  </span>
+                  <span className="text-gray-500">
+                    v{r.version} · {formatDateTime(r.createdAt)}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  )
+}

package/components/dashboard/admin/adminUserDevicesCard.tsx

@@ -0,0 +1,80 @@
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "../../ui/card"
+import { formatLocation } from "../../../lib/request-info"
+
+interface UserDevice {
+  id: string
+  visitorId: string
+  device: string
+  ipAddress: string | null
+  country: string | null
+  city: string | null
+  components: Record<string, unknown> | null
+  createdAt: Date
+}
+
+// Signals arrive as whatever FingerprintJS produced: primitives, arrays,
+// nested objects, or { hash } for values too large to store (canvas etc.).
+function formatSignal(value: unknown): string {
+  if (value === null || value === undefined) return "—"
+  if (Array.isArray(value) && value.every((v) => typeof v !== "object")) return value.join(", ") || "—"
+  if (typeof value === "object") return JSON.stringify(value)
+  return String(value)
+}
+
+// Every device this account has signed in from (device_fingerprint rows),
+// each with the FingerprintJS signals behind its visitorId in a collapsible
+// section. Accessibility signals are never collected (lib/device-fingerprint.ts).
+export default function AdminUserDevicesCard({ devices }: { devices: UserDevice[] }) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Devices</CardTitle>
+        <CardDescription>
+          Devices this account has signed in from, with the browser and device signals behind each
+          fingerprint. Only recorded for visitors who allowed the security fingerprint (when consent is required).
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        {devices.length === 0 ? (
+          <p className="text-center text-gray-500 py-8">No devices recorded</p>
+        ) : (
+          <div className="divide-y divide-border rounded-md border border-border">
+            {devices.map((d) => {
+              const signals = d.components ? Object.entries(d.components) : []
+              return (
+                <details key={d.id} className="group p-4">
+                  <summary className="flex cursor-pointer list-none flex-wrap items-center justify-between gap-2">
+                    <div className="min-w-0">
+                      <p className="font-medium">{d.device}</p>
+                      <p className="text-sm text-gray-500">
+                        {formatLocation({ country: d.country, city: d.city })} · {d.ipAddress ?? "Unknown IP"} · first seen{" "}
+                        {d.createdAt.toLocaleString()}
+                      </p>
+                    </div>
+                    <span className="text-sm text-gray-500 group-open:hidden">Show {signals.length} signals</span>
+                    <span className="hidden text-sm text-gray-500 group-open:inline">Hide signals</span>
+                  </summary>
+                  <p className="mt-3 break-all font-mono text-xs text-gray-500">visitorId: {d.visitorId}</p>
+                  {signals.length === 0 ? (
+                    <p className="mt-2 text-sm text-gray-500">
+                      No signals yet. They&apos;re collected the next time this device signs in.
+                    </p>
+                  ) : (
+                    <dl className="mt-3 grid grid-cols-1 gap-x-4 gap-y-1 text-sm sm:grid-cols-[max-content_1fr]">
+                      {signals.map(([name, value]) => (
+                        <div key={name} className="contents">
+                          <dt className="font-mono text-gray-500">{name}</dt>
+                          <dd className="mb-2 break-all font-mono sm:mb-0">{formatSignal(value)}</dd>
+                        </div>
+                      ))}
+                    </dl>
+                  )}
+                </details>
+              )
+            })}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  )
+}

package/components/dashboard/admin/broadcastActions.tsx

@@ -0,0 +1,148 @@
+'use client'
+
+import { useEffect, useState } from "react"
+import { useRouter } from "next/navigation"
+import { toast } from "sonner"
+import { Button } from "../../ui/button"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "../../ui/dialog"
+import ConfirmSendDialog from "./confirmSendDialog"
+
+interface Preview {
+  subject: string | null
+  from: string | null
+  previewText: string | null
+  html: string | null
+  text: string | null
+}
+
+export default function BroadcastActions({ id, name, status }: { id: string; name: string; status: string }) {
+  const router = useRouter()
+  const [open, setOpen] = useState(false)
+  const [preview, setPreview] = useState<Preview | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [sending, setSending] = useState(false)
+  const [confirming, setConfirming] = useState(false)
+
+  const openPreview = async () => {
+    setOpen(true)
+    if (preview) return
+    setLoading(true)
+    try {
+      const response = await fetch(`/api/admin/marketing/${id}`)
+      const data = await response.json()
+      if (!response.ok) throw new Error(data.error || "Failed to load preview")
+      setPreview(data)
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : "Failed to load preview")
+      setOpen(false)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  const send = async () => {
+    setSending(true)
+    try {
+      const response = await fetch(`/api/admin/marketing/${id}`, { method: "POST" })
+      const data = await response.json()
+      if (!response.ok) throw new Error(data.error || "Failed to send broadcast")
+      toast.success("Broadcast sent")
+      setOpen(false)
+      router.refresh()
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : "Failed to send broadcast")
+    } finally {
+      setSending(false)
+    }
+  }
+
+  // Resend has no push for broadcast status, so poll while it's queued and
+  // refresh the list once it moves on (e.g. to "sent").
+  // ponytail: stops after ~5 min; a broadcast scheduled for later stays
+  // "queued" until it goes out, so it's not worth polling that long.
+  useEffect(() => {
+    if (status !== "queued") return
+    let tries = 0
+    const timer = setInterval(async () => {
+      if (++tries > 100) return clearInterval(timer)
+      try {
+        const response = await fetch(`/api/admin/marketing/${id}`)
+        if (!response.ok) return
+        const data = await response.json()
+        if (data.status !== "queued") {
+          clearInterval(timer)
+          router.refresh()
+        }
+      } catch {
+        // network blip, try again next tick
+      }
+    }, 3000)
+    return () => clearInterval(timer)
+  }, [id, status, router])
+
+  const isDraft = status === "draft"
+
+  return (
+    <>
+      {status === "queued" && (
+        <span className="flex items-center gap-1.5 text-xs">
+          <span className="size-2 animate-pulse rounded-full bg-amber-500" />
+          Sending…
+        </span>
+      )}
+      <Button size="sm" variant="outline" onClick={openPreview}>Preview</Button>
+      {isDraft && (
+        <Button size="sm" disabled={sending} onClick={() => setConfirming(true)}>
+          {sending ? "Sending…" : "Send"}
+        </Button>
+      )}
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent className="sm:max-w-2xl">
+          <DialogHeader>
+            <DialogTitle>{preview?.subject || name}</DialogTitle>
+            <DialogDescription>
+              {preview ? `From ${preview.from ?? "—"}${preview.previewText ? ` · ${preview.previewText}` : ""}` : "Loading…"}
+            </DialogDescription>
+          </DialogHeader>
+          {loading ? (
+            <div className="h-[60vh] animate-pulse rounded-md bg-muted" />
+          ) : preview?.html ? (
+            // sandbox="" — no scripts, no navigation out of the frame
+            <iframe
+              title="Email preview"
+              sandbox=""
+              srcDoc={preview.html}
+              className="h-[60vh] w-full rounded-md border bg-white"
+            />
+          ) : (
+            <pre className="h-[60vh] overflow-auto whitespace-pre-wrap rounded-md border p-4 text-sm">
+              {preview?.text ?? ""}
+            </pre>
+          )}
+          {isDraft && (
+            <div className="flex justify-end">
+              <Button disabled={sending || loading} onClick={() => setConfirming(true)}>
+                {sending ? "Sending…" : "Send now"}
+              </Button>
+            </div>
+          )}
+        </DialogContent>
+      </Dialog>
+
+      <ConfirmSendDialog
+        open={confirming}
+        onOpenChange={setConfirming}
+        subject={preview?.subject || name}
+        audience="its segment"
+        onConfirm={send}
+      />
+    </>
+  )
+}

package/components/dashboard/admin/confirmSendDialog.tsx

@@ -0,0 +1,44 @@
+'use client'
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "../../ui/alert-dialog"
+
+export default function ConfirmSendDialog({
+  open,
+  onOpenChange,
+  subject,
+  audience,
+  onConfirm,
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  subject: string
+  audience: string
+  onConfirm: () => void
+}) {
+  return (
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Send this broadcast?</AlertDialogTitle>
+          <AlertDialogDescription>
+            &ldquo;{subject}&rdquo; goes to every subscribed contact in {audience} right away.
+            This can&apos;t be undone.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction onClick={onConfirm}>Send now</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}