@xk2800/nextjs-template 0.7.1-beta.2 → 0.7.1-beta.4

package/README.md

@@ -33,7 +33,7 @@ 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
+- **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
 - **Ops:** `bun run doctor`, Docker image, Doppler support, separate env files for dev, prod and 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/systemSettingsForm.tsx

@@ -52,6 +52,7 @@ export default function SystemSettingsForm({ initialSettings, configuredFlags }:
           authEnableOneTap: settings.authEnableOneTap,
           enableSessionRevocation: settings.enableSessionRevocation,
           feedbackAttachErrors: settings.feedbackAttachErrors,
+          consentRequired: settings.consentRequired ?? true,
         }),
       })
 
@@ -161,6 +162,38 @@ export default function SystemSettingsForm({ initialSettings, configuredFlags }:
         </CardContent>
       </Card>
 
+      <Card>
+        <CardHeader>
+          <CardTitle>Privacy &amp; Consent</CardTitle>
+          <CardDescription>
+            Whether visitors must opt in before device fingerprinting and Google One Tap run
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="flex items-center justify-between gap-4">
+            <div>
+              <Label htmlFor="consent-toggle">Require consent (GDPR / ePrivacy)</Label>
+              <p className="text-sm text-gray-500">
+                On: cookie banner where visitors allow fingerprinting and One Tap separately, and
+                the device record is erased if fingerprint consent is withdrawn. Off: no banner, everything runs for
+                every visitor.
+              </p>
+              {!settings.consentRequired && (
+                <p className="text-sm text-amber-600 dark:text-amber-500">
+                  Only turn this off if none of your users are in the EU, the UK or another region with
+                  consent rules. Fingerprinting without consent breaks those laws.
+                </p>
+              )}
+            </div>
+            <Switch
+              id="consent-toggle"
+              checked={settings.consentRequired ?? true}
+              onCheckedChange={(checked) => setSettings({ ...settings, consentRequired: checked })}
+            />
+          </div>
+        </CardContent>
+      </Card>
+
       <Card>
         <CardHeader>
           <CardTitle>Feedback</CardTitle>

package/components/dashboard/admin/systemSettingsSection.tsx

@@ -1,9 +1,15 @@
-import { getSystemSettings, getConfiguredAuthFlags } from "@xk2800/nextjs-template/settings/queries"
+import { getSystemSettings, getConfiguredAuthFlags, isConsentRequired } from "@xk2800/nextjs-template/settings/queries"
 import SystemSettingsForm from "./systemSettingsForm"
 
 export default async function SystemSettingsSection() {
   const settings = await getSystemSettings()
   const configuredFlags = getConfiguredAuthFlags()
 
-  return <SystemSettingsForm initialSettings={settings} configuredFlags={configuredFlags} />
+  // Show the effective consent mode (null = NEXT_PUBLIC_COOKIE_BANNER default).
+  return (
+    <SystemSettingsForm
+      initialSettings={{ ...settings, consentRequired: isConsentRequired(settings) }}
+      configuredFlags={configuredFlags}
+    />
+  )
 }

package/components/site/cookie-banner.tsx

@@ -6,19 +6,90 @@ import { useEffect, useState } from "react"
 // Relative imports: this file ships raw in the npm package, where `@/` would
 // resolve against the consuming project instead.
 import { Button } from "../ui/button"
-import { COOKIE_BANNER_ENABLED, setCookieConsent, useCookieConsent } from "../../lib/cookie-consent"
+import { Checkbox } from "../ui/checkbox"
+import { Label } from "../ui/label"
+import {
+  readConsent,
+  setCookieConsent,
+  useConsentRequired,
+  useCookieConsent,
+  type ConsentPurpose,
+} from "../../lib/cookie-consent"
+import { CONSENT_VERSION } from "../../lib/cookie-names"
+import { useSession } from "../../lib/auth-client"
+
+// Last choice sent to app/api/consent from this browser, as
+// "userId|choice|version", so each choice is recorded once, not on every load.
+const RECORDED_KEY = "consent-recorded"
+
+// Proof of consent: once a signed-in user has a choice (made now, or before
+// they signed in), record it server-side. The route is idempotent, so a lost
+// localStorage marker only costs one redundant request.
+function useRecordConsent(consentRequired: boolean) {
+  const consent = useCookieConsent()
+  const { data: session } = useSession()
+  const userId = session?.user?.id
+
+  useEffect(() => {
+    if (!consentRequired || !userId || consent === null) return
+    const choice = readConsent()
+    if (!choice) return
+    const marker = `${userId}|${choice}|${CONSENT_VERSION}`
+    try {
+      if (localStorage.getItem(RECORDED_KEY) === marker) return
+    } catch {
+      // No localStorage — fall through; the route dedupes.
+    }
+    fetch("/api/consent", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ choice }),
+    })
+      .then((res) => {
+        if (!res.ok) return
+        try {
+          localStorage.setItem(RECORDED_KEY, marker)
+        } catch {
+          // ignore
+        }
+      })
+      .catch(() => {})
+  }, [consentRequired, userId, consent])
+}
+
+const PURPOSES: { id: ConsentPurpose; label: string; description: string }[] = [
+  {
+    id: "fingerprint",
+    label: "Security fingerprint",
+    description:
+      "A device identifier built from your browser and device characteristics, used to alert you about sign-ins from new devices and to block repeated failed sign-ins.",
+  },
+  {
+    id: "onetap",
+    label: "Google One Tap",
+    description: "Quick sign-in with Google. Loads a Google script that may set Google's own cookies.",
+  },
+]
 
 // Mount once in the root layout. Shows until the visitor picks an option;
 // "Necessary only" is as prominent as "Accept all" on purpose — GDPR requires
-// rejecting to be as easy as accepting.
+// rejecting to be as easy as accepting. "Customize" gives one choice per
+// purpose, unticked by default (pre-ticked boxes aren't valid consent).
 export function CookieBanner() {
   const consent = useCookieConsent()
+  const consentRequired = useConsentRequired()
+  const [customizing, setCustomizing] = useState(false)
+  const [picked, setPicked] = useState<ConsentPurpose[]>([])
   // useCookieConsent() is null on the server *and* before a choice, so wait
   // for mount to tell them apart — otherwise returning visitors see a flash.
   const [mounted, setMounted] = useState(false)
   useEffect(() => setMounted(true), [])
+  useRecordConsent(consentRequired)
+
+  if (!consentRequired || !mounted || consent) return null
 
-  if (!COOKIE_BANNER_ENABLED || !mounted || consent) return null
+  const toggle = (id: ConsentPurpose, on: boolean) =>
+    setPicked((prev) => (on ? [...prev, id] : prev.filter((p) => p !== id)))
 
   return (
     <div
@@ -28,16 +99,46 @@ export function CookieBanner() {
       className="fixed inset-x-4 bottom-4 z-50 mx-auto max-w-lg rounded-lg border border-border bg-background p-4 shadow-lg"
     >
       <p className="text-sm text-muted-foreground">
-        We use necessary cookies to keep you signed in. With your permission we also use a device
-        fingerprint to detect suspicious sign-ins, and Google One Tap sign-in.{" "}
+        We use necessary cookies to keep you signed in. With your permission we also use a security
+        fingerprint, built from your browser and device characteristics, to detect suspicious
+        sign-ins, and Google One Tap sign-in. You can allow each separately.{" "}
         <Link href="/privacy" className="underline underline-offset-4 hover:text-foreground">
           Privacy policy
         </Link>
       </p>
-      <div className="mt-3 flex justify-end gap-2">
+
+      {customizing && (
+        <div className="mt-3 space-y-3">
+          {PURPOSES.map((p) => (
+            <div key={p.id} className="flex items-start gap-3">
+              <Checkbox
+                id={`consent-${p.id}`}
+                checked={picked.includes(p.id)}
+                onCheckedChange={(checked) => toggle(p.id, checked === true)}
+                className="mt-0.5"
+              />
+              <div>
+                <Label htmlFor={`consent-${p.id}`}>{p.label}</Label>
+                <p className="text-xs text-muted-foreground">{p.description}</p>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      <div className="mt-3 flex flex-wrap justify-end gap-2">
         <Button variant="outline" size="sm" onClick={() => setCookieConsent("necessary")}>
           Necessary only
         </Button>
+        {customizing ? (
+          <Button variant="outline" size="sm" onClick={() => setCookieConsent(picked)}>
+            Save choices
+          </Button>
+        ) : (
+          <Button variant="outline" size="sm" onClick={() => setCustomizing(true)}>
+            Customize
+          </Button>
+        )}
         <Button size="sm" onClick={() => setCookieConsent("all")}>
           Accept all
         </Button>
@@ -48,7 +149,8 @@ export function CookieBanner() {
 
 // Withdrawing consent must be as easy as giving it — this reopens the banner.
 export function CookieSettingsButton({ className }: { className?: string }) {
-  if (!COOKIE_BANNER_ENABLED) return null
+  const consentRequired = useConsentRequired()
+  if (!consentRequired) return null
   return (
     <button type="button" className={className} onClick={() => setCookieConsent(null)}>
       Cookie settings