@ingram-tech/bot-protection 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @ingram-tech/bot-protection
+
+Invisible, layered bot protection for forms — no CAPTCHA. Three layers, cheapest
+first:
+
+1. **Honeypot** — a hidden field real users never fill; bots do. Zero-dep.
+2. **Signed timing token** — an HMAC-signed timestamp; rejects submissions that
+   arrive implausibly fast or stale. Zero-dep (`node:crypto`).
+3. **Vercel BotID** — optional, invisible server check. Degrades to a no-op when
+   `botid` isn't installed or you're off Vercel.
+
+## Install
+
+```bash
+bun add @ingram-tech/bot-protection
+# optional, for layer 3:
+bun add botid
+```
+
+Set `BOT_PROTECTION_SECRET` (e.g. `openssl rand -hex 32`).
+
+## Use
+
+**Render the form** (token is minted server-side):
+
+```tsx
+import { createFormToken } from "@ingram-tech/bot-protection";
+import { HoneypotField } from "@ingram-tech/bot-protection/honeypot";
+
+export default function ContactPage() {
+	const token = createFormToken(); // server component / server-side
+	return (
+		<form action="/api/contact" method="post">
+			{/* ...your real fields... */}
+			<HoneypotField token={token} />
+			<button type="submit">Send</button>
+		</form>
+	);
+}
+```
+
+**Verify on submit** (API route or server action):
+
+```ts
+import { verifyHuman } from "@ingram-tech/bot-protection";
+
+export async function POST(request: Request) {
+	const formData = await request.formData();
+	const result = await verifyHuman({ formData });
+	if (!result.ok) {
+		// Silently drop — respond 200 without acting, so bots aren't told why.
+		return Response.json({ ok: true });
+	}
+	// ...send the email / save the lead...
+	return Response.json({ ok: true });
+}
+```
+
+`verifyHuman` also accepts a plain object (`{ formData: { ...fields } }`) and a
+`timing` window (`{ minMs, maxMs }`). Pass `botid: false` to skip layer 3.
+
+## Vercel BotID wiring (per app, layer 3 only)
+
+```ts
+// next.config.ts
+import { withBotId } from "botid/next/config";
+export default withBotId({ /* your config */ });
+```
+
+```ts
+// instrumentation-client.ts
+import { initBotId } from "botid/client/core";
+initBotId({ protect: [{ path: "/api/contact", method: "POST" }] });
+```
+
+## Why "silently drop"?
+
+Returning success without acting (rather than a 4xx) avoids teaching spam tools
+which layer caught them — which is what makes them give up.

package/dist/botid.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thin wrapper around Vercel BotID's server check.
+ *
+ * `botid` is an optional peer dependency, and BotID only does real work on
+ * Vercel. We import it dynamically via a non-literal specifier so:
+ *   - the package builds without `botid` installed, and
+ *   - if it isn't installed (or the call throws off-Vercel/in dev), we degrade
+ *     to "not a bot" rather than blocking real users.
+ *
+ * App-side wiring (per site, not in this package): add `withBotId(nextConfig)`
+ * in next.config and `initBotId({ protect: [...] })` in instrumentation-client.
+ */
+export declare const checkBot: () => Promise<{
+    isBot: boolean;
+}>;
+//# sourceMappingURL=botid.d.ts.map

package/dist/botid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"botid.d.ts","sourceRoot":"","sources":["../src/botid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,QAAQ,QAAa,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAW3D,CAAC"}

package/dist/botid.js

@@ -0,0 +1,24 @@
+/**
+ * Thin wrapper around Vercel BotID's server check.
+ *
+ * `botid` is an optional peer dependency, and BotID only does real work on
+ * Vercel. We import it dynamically via a non-literal specifier so:
+ *   - the package builds without `botid` installed, and
+ *   - if it isn't installed (or the call throws off-Vercel/in dev), we degrade
+ *     to "not a bot" rather than blocking real users.
+ *
+ * App-side wiring (per site, not in this package): add `withBotId(nextConfig)`
+ * in next.config and `initBotId({ protect: [...] })` in instrumentation-client.
+ */
+export const checkBot = async () => {
+    try {
+        // Non-literal specifier: keeps tsc from requiring `botid` at build time.
+        const specifier = "botid/server";
+        const mod = (await import(specifier));
+        return await mod.checkBotId();
+    }
+    catch {
+        return { isBot: false };
+    }
+};
+//# sourceMappingURL=botid.js.map

package/dist/botid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"botid.js","sourceRoot":"","sources":["../src/botid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,IAAiC,EAAE;IAC/D,IAAI,CAAC;QACJ,yEAAyE;QACzE,MAAM,SAAS,GAAG,cAAc,CAAC;QACjC,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAEnC,CAAC;QACF,OAAO,MAAM,GAAG,CAAC,UAAU,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;AACF,CAAC,CAAC"}

package/dist/fields.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared field names used by the honeypot component and the server verifier.
+ * Kept in one place so the client and server never drift.
+ */
+/** Hidden field real users never fill; bots auto-complete it. */
+export declare const HONEYPOT_FIELD = "company_url";
+/** Hidden field carrying the signed timing token. */
+export declare const TOKEN_FIELD = "_bp_token";
+//# sourceMappingURL=fields.d.ts.map

package/dist/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iEAAiE;AACjE,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAE5C,qDAAqD;AACrD,eAAO,MAAM,WAAW,cAAc,CAAC"}

package/dist/fields.js

@@ -0,0 +1,9 @@
+/**
+ * Shared field names used by the honeypot component and the server verifier.
+ * Kept in one place so the client and server never drift.
+ */
+/** Hidden field real users never fill; bots auto-complete it. */
+export const HONEYPOT_FIELD = "company_url";
+/** Hidden field carrying the signed timing token. */
+export const TOKEN_FIELD = "_bp_token";
+//# sourceMappingURL=fields.js.map

package/dist/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C,qDAAqD;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC"}

package/dist/honeypot.d.ts

@@ -0,0 +1,4 @@
+export declare const HoneypotField: ({ token }: {
+    token: string;
+}) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=honeypot.d.ts.map

package/dist/honeypot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"honeypot.d.ts","sourceRoot":"","sources":["../src/honeypot.tsx"],"names":[],"mappings":"AAuBA,eAAO,MAAM,aAAa,GAAI,WAAW;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,4CAczD,CAAC"}

package/dist/honeypot.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HONEYPOT_FIELD, TOKEN_FIELD } from "./fields";
+/**
+ * Visually-hidden honeypot + signed timing token, dropped inside any <form>.
+ *
+ * Presentational only (no client JS), so it renders fine in server or client
+ * components. Pass a `token` minted server-side with `createFormToken()`.
+ *
+ * Real users never see or fill the honeypot (off-screen, aria-hidden,
+ * tabIndex -1, autocomplete off); bots that fill every field give themselves
+ * away.
+ */
+const hidden = {
+    position: "absolute",
+    left: "-9999px",
+    top: "-9999px",
+    width: "1px",
+    height: "1px",
+    overflow: "hidden",
+};
+export const HoneypotField = ({ token }) => (_jsxs("div", { "aria-hidden": "true", style: hidden, children: [_jsxs("label", { children: ["Leave this field empty", _jsx("input", { type: "text", name: HONEYPOT_FIELD, tabIndex: -1, autoComplete: "off", defaultValue: "" })] }), _jsx("input", { type: "hidden", name: TOKEN_FIELD, defaultValue: token })] }));
+//# sourceMappingURL=honeypot.js.map

package/dist/honeypot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"honeypot.js","sourceRoot":"","sources":["../src/honeypot.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvD;;;;;;;;;GASG;AAEH,MAAM,MAAM,GAAkB;IAC7B,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,SAAS;IACd,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,KAAK;IACb,QAAQ,EAAE,QAAQ;CAClB,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAAE,KAAK,EAAqB,EAAE,EAAE,CAAC,CAC9D,8BAAiB,MAAM,EAAC,KAAK,EAAE,MAAM,aACpC,sDAEC,gBACC,IAAI,EAAC,MAAM,EACX,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,CAAC,CAAC,EACZ,YAAY,EAAC,KAAK,EAClB,YAAY,EAAC,EAAE,GACd,IACK,EACR,gBAAO,IAAI,EAAC,QAAQ,EAAC,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,GAAI,IAC1D,CACN,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { checkBot } from "./botid";
+export { HONEYPOT_FIELD, TOKEN_FIELD } from "./fields";
+export { isConfigured } from "./keys";
+export { createFormToken, type TokenCheck, type TokenResult, verifyFormToken, } from "./token";
+export { type VerifyOptions, type VerifyResult, verifyHuman } from "./verify";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EACN,eAAe,EACf,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,eAAe,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Server entry. The honeypot component lives at "@ingram-tech/bot-protection/honeypot"
+// so importing the verifier server-side never pulls in React.
+export { checkBot } from "./botid";
+export { HONEYPOT_FIELD, TOKEN_FIELD } from "./fields";
+export { isConfigured } from "./keys";
+export { createFormToken, verifyFormToken, } from "./token";
+export { verifyHuman } from "./verify";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,8DAA8D;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EACN,eAAe,EAGf,eAAe,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAyC,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Environment contract for @ingram-tech/bot-protection.
+ *
+ * BOT_PROTECTION_SECRET — secret used to HMAC-sign the timing token so bots
+ * can't forge a "this form was rendered long enough ago" claim. Generate with
+ * e.g. `openssl rand -hex 32`.
+ */
+export declare const getSecret: () => string;
+/** Whether the signed-timing layer is configured. */
+export declare const isConfigured: () => boolean;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,SAAS,QAAO,MAQ5B,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,YAAY,QAAO,OAAqD,CAAC"}

package/dist/keys.js

@@ -0,0 +1,17 @@
+/**
+ * Environment contract for @ingram-tech/bot-protection.
+ *
+ * BOT_PROTECTION_SECRET — secret used to HMAC-sign the timing token so bots
+ * can't forge a "this form was rendered long enough ago" claim. Generate with
+ * e.g. `openssl rand -hex 32`.
+ */
+export const getSecret = () => {
+    const secret = process.env.BOT_PROTECTION_SECRET;
+    if (!secret) {
+        throw new Error("@ingram-tech/bot-protection: BOT_PROTECTION_SECRET is not configured");
+    }
+    return secret;
+};
+/** Whether the signed-timing layer is configured. */
+export const isConfigured = () => Boolean(process.env.BOT_PROTECTION_SECRET);
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAW,EAAE;IACrC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IACjD,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACd,sEAAsE,CACtE,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC,CAAC;AAEF,qDAAqD;AACrD,MAAM,CAAC,MAAM,YAAY,GAAG,GAAY,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC"}

package/dist/token.d.ts

@@ -0,0 +1,15 @@
+/** Mint a token. Call server-side when rendering the form. */
+export declare const createFormToken: () => string;
+export interface TokenCheck {
+    /** Reject submissions faster than this (default 2000ms — bots are instant). */
+    minMs?: number;
+    /** Reject tokens older than this (default 1h — stale/replayed forms). */
+    maxMs?: number;
+}
+export interface TokenResult {
+    ok: boolean;
+    reason?: string;
+}
+/** Verify a token's signature and that it falls inside the timing window. */
+export declare const verifyFormToken: (token: string | undefined | null, { minMs, maxMs }?: TokenCheck) => TokenResult;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAYA,8DAA8D;AAC9D,eAAO,MAAM,eAAe,QAAO,MAGlC,CAAC;AAEF,MAAM,WAAW,UAAU;IAC1B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6EAA6E;AAC7E,eAAO,MAAM,eAAe,GAC3B,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,EAChC,mBAA0C,UAAe,KACvD,WAqBF,CAAC"}

package/dist/token.js

@@ -0,0 +1,38 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { getSecret } from "./keys";
+/**
+ * Signed timing token: `<timestamp>.<hmac>`. The timestamp records when the
+ * form was rendered; the HMAC (keyed by BOT_PROTECTION_SECRET) prevents a bot
+ * from forging an older timestamp to defeat the "submitted too fast" check.
+ */
+const sign = (ts, secret) => createHmac("sha256", secret).update(ts).digest("hex");
+/** Mint a token. Call server-side when rendering the form. */
+export const createFormToken = () => {
+    const ts = Date.now().toString();
+    return `${ts}.${sign(ts, getSecret())}`;
+};
+/** Verify a token's signature and that it falls inside the timing window. */
+export const verifyFormToken = (token, { minMs = 2000, maxMs = 60 * 60 * 1000 } = {}) => {
+    if (!token)
+        return { ok: false, reason: "missing-token" };
+    const dot = token.indexOf(".");
+    if (dot <= 0)
+        return { ok: false, reason: "malformed-token" };
+    const ts = token.slice(0, dot);
+    const sig = token.slice(dot + 1);
+    const expected = sign(ts, getSecret());
+    const a = Buffer.from(sig);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+        return { ok: false, reason: "bad-signature" };
+    }
+    const elapsed = Date.now() - Number(ts);
+    if (!Number.isFinite(elapsed))
+        return { ok: false, reason: "bad-timestamp" };
+    if (elapsed < minMs)
+        return { ok: false, reason: "too-fast" };
+    if (elapsed > maxMs)
+        return { ok: false, reason: "expired" };
+    return { ok: true };
+};
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;;GAIG;AAEH,MAAM,IAAI,GAAG,CAAC,EAAU,EAAE,MAAc,EAAU,EAAE,CACnD,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEvD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,eAAe,GAAG,GAAW,EAAE;IAC3C,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;IACjC,OAAO,GAAG,EAAE,IAAI,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;AACzC,CAAC,CAAC;AAcF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,eAAe,GAAG,CAC9B,KAAgC,EAChC,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,KAAiB,EAAE,EAC3C,EAAE;IAChB,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1D,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC9D,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAEjC,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACvC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACrD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC7E,IAAI,OAAO,GAAG,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC9D,IAAI,OAAO,GAAG,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAE7D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACrB,CAAC,CAAC"}

package/dist/verify.d.ts

@@ -0,0 +1,26 @@
+import { type TokenCheck } from "./token";
+export interface VerifyResult {
+    ok: boolean;
+    /** Which layer rejected: "honeypot" | token reason | "botid". */
+    reason?: string;
+}
+export interface VerifyOptions {
+    /** Submitted form data — a FormData or a plain object. */
+    formData: FormData | Record<string, unknown>;
+    /** Timing window for the signed token. */
+    timing?: TokenCheck;
+    /** Run the Vercel BotID layer (default true). Set false to skip. */
+    botid?: boolean;
+}
+/**
+ * Run all configured layers in order (cheapest first):
+ *   1. honeypot — the hidden field must be empty
+ *   2. signed timing token — valid signature + plausible timing
+ *   3. Vercel BotID — optional, invisible
+ *
+ * Returns `{ ok: false, reason }` on the first failure. Callers should treat a
+ * failure as "silently drop" (respond 200 without acting) so bots aren't told
+ * what tripped them.
+ */
+export declare const verifyHuman: (options: VerifyOptions) => Promise<VerifyResult>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAmB,MAAM,SAAS,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC7B,0DAA0D;IAC1D,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,0CAA0C;IAC1C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAUD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAU,SAAS,aAAa,KAAG,OAAO,CAAC,YAAY,CAiB9E,CAAC"}

package/dist/verify.js

@@ -0,0 +1,34 @@
+import { checkBot } from "./botid";
+import { HONEYPOT_FIELD, TOKEN_FIELD } from "./fields";
+import { verifyFormToken } from "./token";
+const getField = (formData, name) => {
+    const value = formData instanceof FormData
+        ? formData.get(name)
+        : formData[name];
+    return typeof value === "string" ? value : "";
+};
+/**
+ * Run all configured layers in order (cheapest first):
+ *   1. honeypot — the hidden field must be empty
+ *   2. signed timing token — valid signature + plausible timing
+ *   3. Vercel BotID — optional, invisible
+ *
+ * Returns `{ ok: false, reason }` on the first failure. Callers should treat a
+ * failure as "silently drop" (respond 200 without acting) so bots aren't told
+ * what tripped them.
+ */
+export const verifyHuman = async (options) => {
+    if (getField(options.formData, HONEYPOT_FIELD).trim() !== "") {
+        return { ok: false, reason: "honeypot" };
+    }
+    const token = verifyFormToken(getField(options.formData, TOKEN_FIELD), options.timing);
+    if (!token.ok)
+        return token;
+    if (options.botid !== false) {
+        const { isBot } = await checkBot();
+        if (isBot)
+            return { ok: false, reason: "botid" };
+    }
+    return { ok: true };
+};
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAmB,eAAe,EAAE,MAAM,SAAS,CAAC;AAiB3D,MAAM,QAAQ,GAAG,CAAC,QAAmC,EAAE,IAAY,EAAU,EAAE;IAC9E,MAAM,KAAK,GACV,QAAQ,YAAY,QAAQ;QAC3B,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;QACpB,CAAC,CAAE,QAAoC,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/C,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,OAAsB,EAAyB,EAAE;IAClF,IAAI,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC9D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,KAAK,GAAG,eAAe,CAC5B,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,EACvC,OAAO,CAAC,MAAM,CACd,CAAC;IACF,IAAI,CAAC,KAAK,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IAE5B,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;QAC7B,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,QAAQ,EAAE,CAAC;QACnC,IAAI,KAAK;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAClD,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACrB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@ingram-tech/bot-protection",
+	"version": "0.1.0",
+	"description": "Invisible, layered bot protection for forms — honeypot + signed timing token + Vercel BotID.",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ingram-technologies/nextkit.git",
+		"directory": "packages/bot-protection"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./honeypot": {
+			"types": "./dist/honeypot.d.ts",
+			"import": "./dist/honeypot.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"type-check": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run"
+	},
+	"devDependencies": {
+		"@ingram-tech/typescript-config": "0.1.0",
+		"@types/node": "^20.0.0",
+		"@types/react": "^19.0.0",
+		"react": "^19.0.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.6"
+	},
+	"peerDependencies": {
+		"botid": ">=1.0.0",
+		"react": "^18.0.0 || ^19.0.0"
+	},
+	"peerDependenciesMeta": {
+		"botid": {
+			"optional": true
+		},
+		"react": {
+			"optional": true
+		}
+	}
+}