@gravixar/forms 0.1.0 → 0.2.0

package/README.md

@@ -17,8 +17,8 @@ booking endpoint behind BotID.
 
 ## Two entry points
 
-- `@gravixar/forms`: client-safe. The field names a form renders, and the types. A test walks this entry's module
-  graph and fails if it reaches server code, because a client component ships everything it imports.
+- `@gravixar/forms`: client-safe. The field names a form renders, the form clock, and the types. A test walks this
+  entry's module graph and fails if it reaches server code, because a client component ships everything it imports.
 - `@gravixar/forms/server`: everything that runs a submission.
 
 ## Define
@@ -39,7 +39,7 @@ export const enquiry = defineForm({
       email: z.union([z.literal(""), z.email(msg.email[locale])]),
       message: z.string().trim().min(1, msg.message[locale]).max(5000),
     }),
-  // Optional. Default: honeypot "website", time trap on "ts" (2 s to 24 h), no BotID.
+  // Optional. Default: honeypot "website", time trap on "te", else "ts" (2 s min; 24 h max for "ts"), no BotID.
   gate: { botId: checkBotId },
   // Optional: parts hashed into the id. Omit for a random id.
   dedupe: (data) => [normalizeEmail(data.email), data.name],
@@ -87,16 +87,58 @@ never `null`, and treats an empty file input as absent. List repeated fields in
 ## Render
 
 ```tsx
-import { HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "@gravixar/forms";
-
-<div className="hp" aria-hidden="true">
-  <label>Website<input {...honeypotInputProps} /></label>
-</div>
-<input type="hidden" name={TIMESTAMP_FIELD} value={renderedAt} /> {/* Date.now(), set once on mount */}
+"use client";
+import { useActionState, useEffect, useRef } from "react";
+import {
+  ELAPSED_FIELD,
+  TIMESTAMP_FIELD,
+  createFormClock,
+  honeypotInputProps,
+  type FormClock,
+  type FormState,
+} from "@gravixar/forms";
+import { submitEnquiry } from "@/app/actions";
+
+export function EnquiryForm() {
+  const [state, action] = useActionState(submitEnquiry, { status: "idle" } as FormState);
+  const clock = useRef<FormClock | null>(null);
+  useEffect(() => {
+    clock.current = createFormClock(); // when the form mounts
+  }, []);
+  useEffect(() => {
+    if (state.status === "ok") clock.current?.reset(); // a second enquiry from this tab is timed from now
+  }, [state]);
+
+  return (
+    <form action={action} onSubmit={(e) => clock.current?.stamp(e.currentTarget)}>
+      {/* the form's own fields */}
+      <div className="hp" aria-hidden="true">
+        <label>Website<input {...honeypotInputProps} /></label>
+      </div>
+      <input type="hidden" name={TIMESTAMP_FIELD} />
+      <input type="hidden" name={ELAPSED_FIELD} />
+    </form>
+  );
+}
 ```
 
-Put the honeypot off-screen with CSS, not `display: none`, which some bots skip. **A form without the timestamp is
-ignored**, so add it before switching a live form over.
+Put the honeypot off-screen with CSS, not `display: none`, which some bots skip.
+
+`createFormClock()` has no dependencies and no React in it. `stamp(form)` writes both time fields into the form's
+inputs when it is submitted, adding a hidden input for either one the form doesn't render. React builds a form
+action's `FormData` after `onSubmit` runs, so the stamped values are the ones sent. A form that posts with `fetch`
+calls `clock.stamp(formData)` instead, which sets both fields on its `FormData`. `clock.fields()` returns them as
+`{ ts, te }`.
+
+**Why two time fields.** `ts` is the time the form opened by the device's clock, and the gate compares it with the
+server's clock. A phone whose clock runs a few minutes fast makes a person look faster than two seconds, and one
+whose tab stayed open for more than a day looks stale. Either way the gate ignores them while they see "sent".
+`te` is how long the form was open, measured in the browser from start to finish, so a wrong clock cancels out, and
+it has no age limit. **When a form sends a usable `te` (a finite, non-negative number), the gate uses it and
+ignores `ts`. Otherwise, whether `te` is missing or unusable, `ts` is checked as before.** An unusable `te` is
+never rejected on its own: a hand-rolled timer can go negative when the device's clock is corrected, and a bot gains
+nothing because it could leave `te` out. A form that sends neither field is ignored, so add them before switching a
+live form over. Send both: `ts` keeps the form working against a server still on 0.1.
 
 ## Delivery steps
 

package/dist/clock.d.ts

@@ -0,0 +1,23 @@
+/** Times a form in the browser, for the gate's time trap. Create it when the form mounts. */
+export interface FormClock {
+    /**
+     * Both time fields, as strings: `ts`, the time the form opened by the device's clock, and `te`, how long it has
+     * been open in milliseconds.
+     */
+    fields(): {
+        ts: string;
+        te: string;
+    };
+    /**
+     * Writes both fields into `FormData`, replacing any value, or into a form's inputs of those names, adding a hidden
+     * input for any that is missing. Call it in the form's `submit` handler.
+     */
+    stamp(target: FormData | HTMLFormElement): void;
+    /** Starts timing from now. Call it after a successful submission, so the next one from the same tab is timed anew. */
+    reset(): void;
+}
+/**
+ * A clock for one form. It measures how long the form was open with `performance.now()`, which never jumps when the
+ * device's clock is corrected, so the elapsed time is never negative and doesn't depend on the clock being right.
+ */
+export declare function createFormClock(): FormClock;

package/dist/clock.js

@@ -0,0 +1,37 @@
+import { ELAPSED_FIELD, TIMESTAMP_FIELD } from "./fields.js";
+/**
+ * A clock for one form. It measures how long the form was open with `performance.now()`, which never jumps when the
+ * device's clock is corrected, so the elapsed time is never negative and doesn't depend on the clock being right.
+ */
+export function createFormClock() {
+    let openedAt = 0;
+    let start = 0;
+    function reset() {
+        openedAt = Date.now();
+        start = monotonic();
+    }
+    function fields() {
+        return { [TIMESTAMP_FIELD]: String(openedAt), [ELAPSED_FIELD]: String(Math.round(monotonic() - start)) };
+    }
+    function stamp(target) {
+        for (const [name, value] of Object.entries(fields())) {
+            if (!("elements" in target)) {
+                target.set(name, value);
+                continue;
+            }
+            let input = target.elements.namedItem(name);
+            if (!input) {
+                input = target.ownerDocument.createElement("input");
+                input.type = "hidden";
+                input.name = name;
+                target.append(input);
+            }
+            input.value = value;
+        }
+    }
+    reset();
+    return { fields, stamp, reset };
+}
+function monotonic() {
+    return typeof performance === "undefined" ? Date.now() : performance.now();
+}

package/dist/fields.d.ts

@@ -1,7 +1,17 @@
 /** The honeypot. It is rendered off-screen, so a person never fills it and a bot that fills every input does. */
 export declare const HONEYPOT_FIELD = "website";
-/** The time the form was rendered, in Unix milliseconds, set once when the form mounts. */
+/**
+ * The time the form was rendered, in Unix milliseconds, set once when the form mounts. It is the browser's clock
+ * compared with the server's, so a device clock that is minutes off skews it. The gate uses it only when
+ * `ELAPSED_FIELD` is absent or unusable.
+ */
 export declare const TIMESTAMP_FIELD = "ts";
+/**
+ * How long the form was open, in milliseconds, measured in the browser at submit. Both ends of the measurement are
+ * the browser's clock, so a device clock that is off doesn't change it. When it is a finite, non-negative number
+ * the gate uses it instead of `TIMESTAMP_FIELD`; anything else is ignored. `createFormClock()` sets both.
+ */
+export declare const ELAPSED_FIELD = "te";
 /**
  * The honeypot name Gravixar's private backend package used. The gate accepts it as well, so forms that render it
  * keep working when that package re-exports this one.

package/dist/fields.js

@@ -4,8 +4,18 @@
  */
 /** The honeypot. It is rendered off-screen, so a person never fills it and a bot that fills every input does. */
 export const HONEYPOT_FIELD = "website";
-/** The time the form was rendered, in Unix milliseconds, set once when the form mounts. */
+/**
+ * The time the form was rendered, in Unix milliseconds, set once when the form mounts. It is the browser's clock
+ * compared with the server's, so a device clock that is minutes off skews it. The gate uses it only when
+ * `ELAPSED_FIELD` is absent or unusable.
+ */
 export const TIMESTAMP_FIELD = "ts";
+/**
+ * How long the form was open, in milliseconds, measured in the browser at submit. Both ends of the measurement are
+ * the browser's clock, so a device clock that is off doesn't change it. When it is a finite, non-negative number
+ * the gate uses it instead of `TIMESTAMP_FIELD`; anything else is ignored. `createFormClock()` sets both.
+ */
+export const ELAPSED_FIELD = "te";
 /**
  * The honeypot name Gravixar's private backend package used. The gate accepts it as well, so forms that render it
  * keep working when that package re-exports this one.

package/dist/form.js

@@ -1,4 +1,4 @@
-import { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD } from "./fields.js";
+import { ELAPSED_FIELD, HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD } from "./fields.js";
 import { checkGate, gateFields } from "./gate.js";
 import { errorMessage, isProduction, randomId, stableId } from "./helpers.js";
 import { blobStep, emailStep } from "./steps.js";
@@ -25,10 +25,20 @@ export function defineForm(definition) {
     if (repeated)
         throw new FormError(`${log} has two delivery steps named "${repeated}". Give one a \`name\`.`);
     const fields = gateFields(gate);
-    if (gate.honeypot !== false && gate.timeTrap !== false) {
+    if (gate.timeTrap !== false) {
         const timestamp = gate.timeTrap?.field ?? TIMESTAMP_FIELD;
-        if ([gate.honeypot ?? HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD].includes(timestamp)) {
-            throw new FormError(`${log} uses "${timestamp}" for both the honeypot and the timestamp.`);
+        const elapsed = gate.timeTrap?.elapsedField ?? ELAPSED_FIELD;
+        if (timestamp === elapsed) {
+            throw new FormError(`${log} uses "${timestamp}" for both the timestamp and the elapsed time.`);
+        }
+        if (gate.honeypot !== false) {
+            const honeypots = [gate.honeypot ?? HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD];
+            if (honeypots.includes(timestamp)) {
+                throw new FormError(`${log} uses "${timestamp}" for both the honeypot and the timestamp.`);
+            }
+            if (honeypots.includes(elapsed)) {
+                throw new FormError(`${log} uses "${elapsed}" for both the honeypot and the elapsed time.`);
+            }
         }
     }
     if (gate.timeTrap) {

package/dist/gate.d.ts

@@ -1,15 +1,22 @@
 import type { GateReason } from "./types.js";
 /** The fastest a person fills a form, in milliseconds. */
 export declare const MIN_FILL_MS = 2000;
-/** A form older than this was cached or replayed, in milliseconds. */
+/** A form older than this was cached or replayed, in milliseconds. Checked only on the timestamp path. */
 export declare const MAX_FORM_AGE_MS: number;
 export interface GateOptions {
     /** The honeypot field. Default `"website"`; `"hp_website"` is always checked too. `false` turns it off. */
     honeypot?: string | false;
-    /** The time trap. On by default, and a missing timestamp fails it. `false` turns it off. */
+    /**
+     * The time trap. On by default. It reads the elapsed field when the form sends a usable one (a finite,
+     * non-negative number), and the timestamp otherwise; a form that sends neither fails it. `false` turns it off.
+     */
     timeTrap?: {
+        /** The timestamp field. Default `"ts"`. */
         field?: string;
+        /** The elapsed-time field. Default `"te"`. */
+        elapsedField?: string;
         minMs?: number;
+        /** Applies to the timestamp only: an elapsed time measured in the browser has no age to check. */
         maxAgeMs?: number;
     } | false;
 }
@@ -25,6 +32,13 @@ export declare function gateFields(options?: GateOptions): string[];
  * The bot gate, on the raw input, before validation: a validator that rejected a filled honeypot would name the
  * field in its error, telling a bot exactly what to leave empty. Pure and synchronous; BotID is a form option.
  *
- * An absent value is `undefined` or `null`. Anything else in the honeypot other than blank text trips it.
+ * An absent value is `undefined`, `null` or `""`. Anything else in the honeypot other than blank text trips it.
+ *
+ * The time trap prefers the elapsed field, which the browser measures against its own clock, so a device clock that
+ * is minutes off can't make a person look too fast or too old. It has no age limit: a tab left open for days is a
+ * person, and a replayed request would carry its old elapsed time anyway. An elapsed value that isn't a finite,
+ * non-negative number is ignored rather than rejected: a hand-rolled `Date.now() - mount` goes negative when the
+ * device's clock is corrected mid-fill, and a bot gains nothing, since it could leave the field out. Without a usable
+ * one, the timestamp is compared with the server's clock, as before.
  */
 export declare function checkGate(input: Record<string, unknown>, options?: GateOptions, nowMs?: number): GateVerdict;

package/dist/gate.js

@@ -1,22 +1,30 @@
-import { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD } from "./fields.js";
+import { ELAPSED_FIELD, HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD } from "./fields.js";
 /** The fastest a person fills a form, in milliseconds. */
 export const MIN_FILL_MS = 2_000;
-/** A form older than this was cached or replayed, in milliseconds. */
+/** A form older than this was cached or replayed, in milliseconds. Checked only on the timestamp path. */
 export const MAX_FORM_AGE_MS = 24 * 60 * 60 * 1000;
 /** The field names the gate reads, so they can be kept out of validation. */
 export function gateFields(options = {}) {
     const fields = new Set();
     if (options.honeypot !== false)
         fields.add(options.honeypot ?? HONEYPOT_FIELD).add(LEGACY_HONEYPOT_FIELD);
-    if (options.timeTrap !== false)
-        fields.add(options.timeTrap?.field ?? TIMESTAMP_FIELD);
+    if (options.timeTrap !== false) {
+        fields.add(options.timeTrap?.field ?? TIMESTAMP_FIELD).add(options.timeTrap?.elapsedField ?? ELAPSED_FIELD);
+    }
     return [...fields];
 }
 /**
  * The bot gate, on the raw input, before validation: a validator that rejected a filled honeypot would name the
  * field in its error, telling a bot exactly what to leave empty. Pure and synchronous; BotID is a form option.
  *
- * An absent value is `undefined` or `null`. Anything else in the honeypot other than blank text trips it.
+ * An absent value is `undefined`, `null` or `""`. Anything else in the honeypot other than blank text trips it.
+ *
+ * The time trap prefers the elapsed field, which the browser measures against its own clock, so a device clock that
+ * is minutes off can't make a person look too fast or too old. It has no age limit: a tab left open for days is a
+ * person, and a replayed request would carry its old elapsed time anyway. An elapsed value that isn't a finite,
+ * non-negative number is ignored rather than rejected: a hand-rolled `Date.now() - mount` goes negative when the
+ * device's clock is corrected mid-fill, and a bot gains nothing, since it could leave the field out. Without a usable
+ * one, the timestamp is compared with the server's clock, as before.
  */
 export function checkGate(input, options = {}, nowMs = Date.now()) {
     if (options.honeypot !== false) {
@@ -26,14 +34,15 @@ export function checkGate(input, options = {}, nowMs = Date.now()) {
         }
     }
     if (options.timeTrap !== false) {
-        const { field = TIMESTAMP_FIELD, minMs = MIN_FILL_MS, maxAgeMs = MAX_FORM_AGE_MS } = options.timeTrap ?? {};
+        const { field = TIMESTAMP_FIELD, elapsedField = ELAPSED_FIELD, minMs = MIN_FILL_MS, maxAgeMs = MAX_FORM_AGE_MS, } = options.timeTrap ?? {};
+        const elapsed = elapsedMs(input[elapsedField]);
+        if (elapsed !== undefined)
+            return elapsed < minMs ? { ok: false, reason: "ts_too_fast" } : { ok: true };
         const raw = input[field];
-        if (raw === undefined || raw === null || raw === "")
+        if (absent(raw))
             return { ok: false, reason: "ts_missing" };
-        if (typeof raw !== "string" && typeof raw !== "number")
-            return { ok: false, reason: "ts_invalid" };
-        const ts = Number(raw);
-        if (!Number.isFinite(ts))
+        const ts = toNumber(raw);
+        if (ts === undefined)
             return { ok: false, reason: "ts_invalid" };
         const age = nowMs - ts;
         if (age < minMs)
@@ -43,6 +52,23 @@ export function checkGate(input, options = {}, nowMs = Date.now()) {
     }
     return { ok: true };
 }
+function absent(value) {
+    return value === undefined || value === null || value === "";
+}
+/** A usable elapsed time: a finite, non-negative number or numeric string. Anything else, blank included, is unusable. */
+function elapsedMs(value) {
+    if (typeof value === "string" && value.trim() === "")
+        return undefined;
+    const n = toNumber(value);
+    return n !== undefined && n >= 0 ? n : undefined;
+}
+/** A finite number, from a number or a numeric string; otherwise undefined. */
+function toNumber(value) {
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
 function filled(value) {
     if (value === undefined || value === null)
         return false;

package/dist/index.d.ts

@@ -1,2 +1,4 @@
-export { HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";
+export { createFormClock } from "./clock.js";
+export type { FormClock } from "./clock.js";
+export { ELAPSED_FIELD, HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";
 export type { Evidence, FormState, GateReason, SubmitResult } from "./types.js";

package/dist/index.js

@@ -1,7 +1,8 @@
 /*
- * @gravixar/forms: the client-safe entry. A form component imports the field names and types from here. Everything
- * that runs a submission is in `@gravixar/forms/server`: a client component that imports server code ships it to
- * the browser, so nothing reachable from this file may import a Node builtin or server code. A test walks this
- * entry's module graph to hold that.
+ * @gravixar/forms: the client-safe entry. A form component imports the field names, the form clock and the types
+ * from here. Everything that runs a submission is in `@gravixar/forms/server`: a client component that imports
+ * server code ships it to the browser, so nothing reachable from this file may import a Node builtin or server code.
+ * A test walks this entry's module graph to hold that.
  */
-export { HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";
+export { createFormClock } from "./clock.js";
+export { ELAPSED_FIELD, HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";

package/dist/server.d.ts

@@ -6,6 +6,6 @@ export { fromFormData, metaFromHeaders, normalizeEmail, stableId } from "./helpe
 export type { FormValue } from "./helpers.js";
 export { blobStep, emailStep, resendMailer, toAttachments } from "./steps.js";
 export type { Attachment, BlobStepOptions, EmailStepOptions, LineStore, MailMessage, Mailer, ResendClient } from "./steps.js";
-export { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";
+export { ELAPSED_FIELD, HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";
 export type { StandardIssue, StandardResult, StandardSchema } from "./standard-schema.js";
 export type { Evidence, FormState, GateReason, Submission, SubmissionMeta, SubmitResult } from "./types.js";

package/dist/server.js

@@ -10,4 +10,4 @@ export { defineForm, FormError } from "./form.js";
 export { checkGate, MAX_FORM_AGE_MS, MIN_FILL_MS } from "./gate.js";
 export { fromFormData, metaFromHeaders, normalizeEmail, stableId } from "./helpers.js";
 export { blobStep, emailStep, resendMailer, toAttachments } from "./steps.js";
-export { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";
+export { ELAPSED_FIELD, HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELD, TIMESTAMP_FIELD, honeypotInputProps } from "./fields.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravixar/forms",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Public form submissions for server actions: a bot gate that runs before validation, any Standard Schema validator, stable ids for dedupe, and delivery steps that fail closed in production.",
   "license": "MIT",
   "type": "module",