@flamingo-stack/openframe-frontend-core 0.0.227 → 0.0.228

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.227",
+  "version": "0.0.228",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -132,6 +132,12 @@
       "require": "./dist/utils/index.cjs",
       "default": "./dist/utils/index.js"
     },
+    "./utils/humanity-signals": {
+      "types": "./dist/utils/humanity-signals.d.ts",
+      "import": "./dist/utils/humanity-signals.js",
+      "require": "./dist/utils/humanity-signals.cjs",
+      "default": "./dist/utils/humanity-signals.js"
+    },
     "./styles": {
       "types": "./src/styles/index.d.ts",
       "import": "./src/styles/index.css",

package/src/components/contact/contact-form.tsx

@@ -44,6 +44,8 @@ import {
   Label,
 } from '../ui'
 import { useContactSubmission } from '../../hooks/use-contact-submission'
+import { useHumanitySignals } from '../../hooks/use-humanity-signals'
+import { HoneypotField } from '../ui/honeypot-field'
 import {
   ChatAttachmentAddButton,
   ChatAttachmentChipStrip,
@@ -180,6 +182,10 @@ export function ContactForm({
   // request when `onCustomSubmit` is active.
   const [customSubmitting, setCustomSubmitting] = useState(false)
 
+  // Invisible bot-protection signals (honeypot + timing). Spread into the
+  // submit payload for BOTH the built-in and custom paths; reset on success.
+  const { honeypotInputProps, getSignals, resetSignals } = useHumanitySignals()
+
   const isSubmitting = onCustomSubmit ? customSubmitting : builtInSubmission.isSubmitting
   // `isSuccess` only ever fires on the built-in path; custom callers
   // own their own UX (no "Message Sent!" button-label flicker).
@@ -206,7 +212,7 @@ export function ContactForm({
     if (isSubmitting) return
     if (attachmentsEnabled && attachments.hasInflightUploads) return
     try {
-      const payload = { ...data, ...(rdtCid && { rdt_cid: rdtCid }) }
+      const payload = { ...data, ...(rdtCid && { rdt_cid: rdtCid }), ...getSignals() }
       const readyAttachments = attachmentsEnabled ? attachments.readyAttachments : []
       if (onCustomSubmit) {
         setCustomSubmitting(true)
@@ -220,6 +226,7 @@ export function ContactForm({
       }
       onSubmitSuccess?.()
       reset()
+      resetSignals()
       if (attachmentsEnabled) attachments.clear()
     } catch {
       // Error toast is owned by the active flow:
@@ -287,6 +294,9 @@ export function ContactForm({
         {!showHelpCategory && <input type="hidden" {...register('helpCategory')} />}
         {!showMessage && <input type="hidden" {...register('message')} />}
 
+        {/* Invisible honeypot — real users never fill it; bots that fill every field trip it. */}
+        <HoneypotField {...honeypotInputProps} />
+
         {/* Extra top field (e.g. Subject for ticket forms). Rendered
             outside the schema-driven layout so the caller fully owns
             label / placeholder / state. */}

package/src/components/features/waitlist-form.tsx

@@ -5,6 +5,9 @@ import { Button } from '../ui/button'
 import { CheckboxBlock } from '../ui/checkbox-block'
 import { Input } from '../ui/input'
 import { PhoneInput } from '../ui/phone-input'
+import { HoneypotField } from '../ui/honeypot-field'
+import { useHumanitySignals } from '../../hooks/use-humanity-signals'
+import type { HumanitySignals } from '../../utils/humanity-signals'
 import { useToast } from '../../hooks/use-toast'
 import { cn } from '../../utils/cn'
 import { hasGenericEmailDomain } from '../../utils/generic-domain-utils'
@@ -19,10 +22,12 @@ export interface WaitlistFormProps {
   /** Optional CSS classes for the container */
   className?: string
   /**
-   * Registration handler — called with email and optional E.164 phone.
-   * Must throw on failure (toast is handled by the form).
+   * Registration handler — called with email, optional E.164 phone, and the
+   * invisible bot-protection signals (honeypot + timing) to forward into the
+   * POST body. Must throw on failure (toast is handled by the form). `signals`
+   * is optional for backward compatibility with older callers.
    */
-  onRegister: (email: string, phone?: string) => Promise<void>
+  onRegister: (email: string, phone?: string, signals?: HumanitySignals) => Promise<void>
   /** Whether a registration request is currently in flight */
   isSubmitting?: boolean
   /** Whether registration completed successfully */
@@ -88,6 +93,7 @@ export function WaitlistForm({
   const [phone, setPhone] = useState(defaultPhone)
   const [countryCode, setCountryCode] = useState<CountryCode>('US')
   const { toast } = useToast()
+  const { honeypotInputProps, getSignals, resetSignals } = useHumanitySignals()
   const [smsConsent, setSmsConsent] = useState(false)
   const [isClient, setIsClient] = useState(false)
   const [isPhoneInvalid, setIsPhoneInvalid] = useState(false)
@@ -137,7 +143,8 @@ export function WaitlistForm({
     const finalPhone = phone ? formatPhoneE164(phone, countryCode) : undefined
 
     try {
-      await onRegister(email, finalPhone)
+      await onRegister(email, finalPhone, getSignals())
+      resetSignals()
     } catch {
       // caller's onRegister should handle its own error toasts if needed
     }
@@ -183,6 +190,9 @@ export function WaitlistForm({
         className
       )}
     >
+      {/* Invisible honeypot — real users never fill it; bots that fill every field trip it. */}
+      <HoneypotField {...honeypotInputProps} />
+
       {/* Email Input */}
       <Input
         type="email"

package/src/components/ui/honeypot-field.tsx

@@ -0,0 +1,30 @@
+'use client'
+
+import { forwardRef } from 'react'
+
+/**
+ * HoneypotField — an invisible decoy input for bot detection. Real users never
+ * see or fill it; naive bots that fill every field trip it (the server blocks
+ * any submission where this field is non-empty).
+ *
+ * Made invisible WITHOUT `type="hidden"` / `display:none` (sophisticated bots
+ * skip those): an off-screen, zero-size, aria-hidden, non-focusable,
+ * non-pointer wrapper. Layout utilities only — no colours/hex (ODS-clean). No
+ * <label> (avoids id coupling); `aria-hidden` + `tabIndex={-1}` keep it out of
+ * the accessibility tree and tab order.
+ *
+ * forwardRef so `<HoneypotField {...honeypotInputProps} />` (which carries the
+ * ref from useHumanitySignals) works on both React 18 and 19.
+ */
+export const HoneypotField = forwardRef<HTMLInputElement, { name: string }>(
+  function HoneypotField({ name }, ref) {
+    return (
+      <div
+        aria-hidden="true"
+        className="absolute w-px h-px p-0 -m-px overflow-hidden pointer-events-none opacity-0"
+      >
+        <input ref={ref} type="text" name={name} tabIndex={-1} autoComplete="off" />
+      </div>
+    )
+  },
+)

package/src/components/ui/index.ts

@@ -10,6 +10,7 @@ export * from './checkbox-block'
 export * from './checkbox-with-description'
 export * from './date-picker'
 export * from './field-wrapper'
+export * from './honeypot-field'
 export * from './info-card'
 export * from './info-row'
 export * from './input'

package/src/hooks/index.ts

@@ -27,3 +27,7 @@ export * from './use-access-code-integration'
 
 // OG placeholder URL builder hook (requires host-supplied URL builder)
 export * from './use-og-placeholder'
+
+// Invisible bot-protection client primitive (honeypot ref + submit-timing).
+// Pairs with the server-safe decision fn in `utils/humanity-signals`.
+export * from './use-humanity-signals'

package/src/hooks/use-humanity-signals.ts

@@ -0,0 +1,47 @@
+'use client'
+
+import { useCallback, useRef } from 'react'
+import {
+  HONEYPOT_FIELD,
+  ELAPSED_MS_FIELD,
+  type HumanitySignals,
+} from '../utils/humanity-signals'
+
+/**
+ * useHumanitySignals — client primitive backing the invisible bot-protection
+ * layer. Owns the honeypot <input> ref + a mount timestamp, and exposes the
+ * props to render the field plus a getter that produces the wire object to
+ * merge into a form's POST body. Reused by every public form (contact,
+ * waitlist, ticket, review) so the signal shape lives in exactly one place.
+ *
+ * Usage:
+ *   const { honeypotInputProps, getSignals, resetSignals } = useHumanitySignals()
+ *   // render: <HoneypotField {...honeypotInputProps} />
+ *   // submit: fetch(url, { body: JSON.stringify({ ...formData, ...getSignals() }) })
+ *   // after a successful submit: resetSignals()
+ *
+ * The two signals are origin-independent (they ride in the body), so they keep
+ * working when the form is embedded behind a reverse-proxy / prefixed URL.
+ */
+export function useHumanitySignals() {
+  const ref = useRef<HTMLInputElement>(null)
+  // performance.now() is monotonic (immune to wall-clock skew). SSR-guarded
+  // even though the hook only executes on the client.
+  const mountedAt = useRef<number>(typeof performance !== 'undefined' ? performance.now() : 0)
+
+  const getSignals = useCallback(
+    (): HumanitySignals => ({
+      [HONEYPOT_FIELD]: ref.current?.value ?? '',
+      [ELAPSED_MS_FIELD]:
+        typeof performance !== 'undefined' ? Math.round(performance.now() - mountedAt.current) : 0,
+    }),
+    [],
+  )
+
+  const resetSignals = useCallback(() => {
+    if (ref.current) ref.current.value = ''
+    if (typeof performance !== 'undefined') mountedAt.current = performance.now()
+  }, [])
+
+  return { honeypotInputProps: { ref, name: HONEYPOT_FIELD }, getSignals, resetSignals } as const
+}

package/src/utils/humanity-signals.ts

@@ -0,0 +1,57 @@
+/**
+ * Humanity signals — invisible bot-protection primitives shared by the lib's
+ * public forms (client) and the hub's per-route `verifyHuman` gate (server).
+ *
+ * PURE + React-free on purpose: this module is a tsup SERVER entry (no
+ * "use client" banner) so the hub can import it server-side without pulling a
+ * client-reference boundary — same pattern as `schemas/contact-schema` and
+ * `components/features/mux-origins`.
+ *
+ * Two origin-independent signals travel in the POST body: a honeypot (a hidden
+ * field real users never fill) and timing (ms from form mount to submit).
+ * `evaluateHumanitySignals` is the SINGLE source of truth for the block/allow
+ * decision — the hub imports + calls it rather than re-implementing the rules.
+ */
+
+/** Hidden honeypot field name. Innocuous + autofill-resistant (deliberately NOT name/email). */
+export const HONEYPOT_FIELD = 'contact_url_confirm'
+/** Client-measured ms between form mount and submit. */
+export const ELAPSED_MS_FIELD = 'form_elapsed_ms'
+/** Default minimum fill time (ms). A submit faster than this is treated as a bot. */
+export const DEFAULT_MIN_FILL_MS = 700
+
+/** Keyed wire object produced by `useHumanitySignals().getSignals()` and spread into the POST body. */
+export type HumanitySignals = Record<string, string | number>
+
+/** Result of {@link evaluateHumanitySignals}. */
+export type HumanityVerdict = { ok: true } | { ok: false; reason: 'honeypot' | 'too_fast' }
+
+/** Tolerant reader — never throws; missing/garbage timing → null. */
+export function extractHumanitySignals(body: unknown): { honeypot: string; elapsedMs: number | null } {
+  const b = (body ?? {}) as Record<string, unknown>
+  const rawHp = b[HONEYPOT_FIELD]
+  // A legit client always sends a STRING here (getSignals → ref.value ?? ''),
+  // so ANY present non-string value is a bot filling the decoy with a non-string
+  // to dodge the empty-check — coerce to a (non-empty) string so it still trips.
+  // null/undefined → '' = the correct "field absent / unfilled" allow case.
+  const honeypot = rawHp == null ? '' : String(rawHp)
+  const rawMs = b[ELAPSED_MS_FIELD]
+  const elapsedMs = typeof rawMs === 'number' && Number.isFinite(rawMs) ? rawMs : null
+  return { honeypot, elapsedMs }
+}
+
+/**
+ * SINGLE decision fn for honeypot + timing (the hub's `verifyHuman` imports + calls this):
+ * - honeypot non-empty → bot (real users never fill the off-screen field)
+ * - elapsed below `minFillMs` → bot (humans take time; a MISSING timing value never blocks)
+ */
+export function evaluateHumanitySignals(body: unknown, opts: { minFillMs: number }): HumanityVerdict {
+  const { honeypot, elapsedMs } = extractHumanitySignals(body)
+  if (honeypot.trim() !== '') return { ok: false, reason: 'honeypot' }
+  if (elapsedMs !== null && elapsedMs < opts.minFillMs) return { ok: false, reason: 'too_fast' }
+  return { ok: true }
+}
+
+/** Parse a comma-separated env string → trimmed, non-empty entries (undefined → []). */
+export const splitCsvEnv = (s?: string): string[] =>
+  s?.split(',').map((t) => t.trim()).filter(Boolean) ?? []

package/src/utils/index.ts

@@ -242,3 +242,9 @@ export {
   type ContentHrefOptions,
   type ComposeContentUrl,
 } from './content-href'
+
+// Invisible bot-protection signals (honeypot + timing) — pure + server-safe so
+// the hub's per-route `verifyHuman` gate imports the SAME `evaluateHumanitySignals`
+// decision fn the lib forms feed. Also exported via the granular subpath
+// `./utils/humanity-signals` for server-only consumers.
+export * from './humanity-signals'