@uranotools/urano-social 0.2.0 → 0.3.0

package/dist/server/antiSpam.js

@@ -0,0 +1,204 @@
+import { randomId, signHmacHex, verifyHmacHex } from '../crypto';
+import { DEFAULT_HONEYPOT_FIELD, DEFAULT_RECAPTCHA_ACTION, } from '../types';
+export { DEFAULT_HONEYPOT_FIELD, DEFAULT_RECAPTCHA_ACTION };
+export const DEFAULT_RECAPTCHA_MIN_SCORE = 0.5;
+export const DEFAULT_CONTACT_MIN_AGE_MS = 2500;
+export const DEFAULT_CONTACT_MAX_AGE_MS = 30 * 60 * 1000;
+export const DEFAULT_CONTACT_MAX_PER_HOUR = 5;
+export const DEFAULT_CONTACT_MAX_MESSAGE_CHARS = 4000;
+/** Process-local buckets (good enough for single Node / Pages isolate). */
+const rateBuckets = new Map();
+export function resolveAntiSpamConfig(partial) {
+    const enabledEnv = process.env.URANO_SOCIAL_ANTISPAM;
+    const enabled = partial?.enabled ?? (enabledEnv == null ? true : !['0', 'false', 'off'].includes(enabledEnv.toLowerCase()));
+    const recaptchaSecret = partial?.recaptchaSecret
+        || process.env.URANO_SOCIAL_RECAPTCHA_SECRET
+        || process.env.RECAPTCHA_SECRET_KEY
+        || '';
+    const minScoreRaw = partial?.recaptchaMinScore
+        ?? (process.env.URANO_SOCIAL_RECAPTCHA_MIN_SCORE
+            ? Number(process.env.URANO_SOCIAL_RECAPTCHA_MIN_SCORE)
+            : DEFAULT_RECAPTCHA_MIN_SCORE);
+    const maxPerHourRaw = partial?.maxPerHour
+        ?? (process.env.URANO_SOCIAL_CONTACT_MAX_PER_HOUR
+            ? Number(process.env.URANO_SOCIAL_CONTACT_MAX_PER_HOUR)
+            : DEFAULT_CONTACT_MAX_PER_HOUR);
+    return {
+        enabled,
+        honeypotField: partial?.honeypotField || process.env.URANO_SOCIAL_HONEYPOT_FIELD || DEFAULT_HONEYPOT_FIELD,
+        minSubmitAgeMs: partial?.minSubmitAgeMs
+            ?? (process.env.URANO_SOCIAL_CONTACT_MIN_AGE_MS
+                ? Number(process.env.URANO_SOCIAL_CONTACT_MIN_AGE_MS)
+                : DEFAULT_CONTACT_MIN_AGE_MS),
+        maxSubmitAgeMs: partial?.maxSubmitAgeMs
+            ?? (process.env.URANO_SOCIAL_CONTACT_MAX_AGE_MS
+                ? Number(process.env.URANO_SOCIAL_CONTACT_MAX_AGE_MS)
+                : DEFAULT_CONTACT_MAX_AGE_MS),
+        maxPerHour: Number.isFinite(maxPerHourRaw) ? Math.max(1, maxPerHourRaw) : DEFAULT_CONTACT_MAX_PER_HOUR,
+        maxMessageChars: partial?.maxMessageChars
+            ?? (process.env.URANO_SOCIAL_CONTACT_MAX_MESSAGE_CHARS
+                ? Number(process.env.URANO_SOCIAL_CONTACT_MAX_MESSAGE_CHARS)
+                : DEFAULT_CONTACT_MAX_MESSAGE_CHARS),
+        recaptchaSecret: recaptchaSecret || undefined,
+        recaptchaMinScore: Number.isFinite(minScoreRaw) ? minScoreRaw : DEFAULT_RECAPTCHA_MIN_SCORE,
+        recaptchaAction: partial?.recaptchaAction
+            || process.env.URANO_SOCIAL_RECAPTCHA_ACTION
+            || DEFAULT_RECAPTCHA_ACTION,
+        requireRecaptcha: partial?.requireRecaptcha
+            ?? (recaptchaSecret
+                ? true
+                : ['1', 'true', 'on'].includes(String(process.env.URANO_SOCIAL_REQUIRE_RECAPTCHA || '').toLowerCase())),
+    };
+}
+export function issueContactTicket(secret, now = Date.now()) {
+    const nonce = randomId('ct');
+    const payload = `${now}.${nonce}`;
+    return `${payload}.${signHmacHex(payload, secret)}`;
+}
+export function verifyContactTicket(ticket, secret, opts, now = Date.now()) {
+    if (!ticket || typeof ticket !== 'string') {
+        return { ok: false, error: 'contact_ticket_required' };
+    }
+    const parts = ticket.split('.');
+    if (parts.length < 3)
+        return { ok: false, error: 'contact_ticket_invalid' };
+    const sig = parts.pop();
+    const payload = parts.join('.');
+    const [issuedRaw] = parts;
+    const issuedAt = Number(issuedRaw);
+    if (!Number.isFinite(issuedAt) || !verifyHmacHex(payload, sig, secret)) {
+        return { ok: false, error: 'contact_ticket_invalid' };
+    }
+    const age = now - issuedAt;
+    if (age < opts.minAgeMs)
+        return { ok: false, error: 'contact_too_fast' };
+    if (age > opts.maxAgeMs)
+        return { ok: false, error: 'contact_ticket_expired' };
+    return { ok: true, issuedAt };
+}
+export function checkContactRateLimit(key, maxPerHour, now = Date.now()) {
+    const bucket = rateBuckets.get(key);
+    if (!bucket || bucket.resetAt <= now) {
+        rateBuckets.set(key, { count: 1, resetAt: now + 60 * 60 * 1000 });
+        return { ok: true };
+    }
+    if (bucket.count >= maxPerHour) {
+        return {
+            ok: false,
+            error: 'contact_rate_limited',
+            retryAfterSec: Math.max(1, Math.ceil((bucket.resetAt - now) / 1000)),
+        };
+    }
+    bucket.count += 1;
+    return { ok: true };
+}
+/** Test helper — clears in-memory rate buckets. */
+export function resetContactRateLimits() {
+    rateBuckets.clear();
+}
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+export function validateContactFields(input) {
+    const email = typeof input.email === 'string' ? input.email.trim().toLowerCase() : '';
+    const message = typeof input.message === 'string' ? input.message.trim() : '';
+    if (!email || !message)
+        return { ok: false, error: 'email_and_message_required' };
+    if (!EMAIL_RE.test(email) || email.length > 254)
+        return { ok: false, error: 'invalid_email' };
+    if (message.length > input.maxMessageChars)
+        return { ok: false, error: 'message_too_long' };
+    return { ok: true, email, message };
+}
+export async function verifyRecaptchaV3(opts) {
+    if (!opts.token)
+        return { ok: false, error: 'recaptcha_required' };
+    const body = new URLSearchParams();
+    body.set('secret', opts.secret);
+    body.set('response', opts.token);
+    if (opts.remoteIp)
+        body.set('remoteip', opts.remoteIp);
+    let data;
+    try {
+        const res = await fetch('https://www.google.com/recaptcha/api/siteverify', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body,
+        });
+        data = await res.json();
+    }
+    catch {
+        return { ok: false, error: 'recaptcha_unreachable' };
+    }
+    if (!data?.success)
+        return { ok: false, error: 'recaptcha_failed' };
+    if (opts.expectedAction && data.action && data.action !== opts.expectedAction) {
+        return { ok: false, error: 'recaptcha_action_mismatch' };
+    }
+    const score = typeof data.score === 'number' ? data.score : 0;
+    if (score < opts.minScore)
+        return { ok: false, error: 'recaptcha_low_score' };
+    return { ok: true, score };
+}
+export function clientIpFromRequest(request) {
+    const forwarded = request.headers.get('cf-connecting-ip')
+        || request.headers.get('x-real-ip')
+        || request.headers.get('x-forwarded-for');
+    if (!forwarded)
+        return null;
+    return forwarded.split(',')[0]?.trim() || null;
+}
+/**
+ * Runs contact anti-spam gates. On honeypot hit returns softOk so the proxy
+ * can fake a success without calling the AI webhook.
+ */
+export async function enforceContactAntiSpam(opts) {
+    const { body, request, visitorId, ticketSecret, config } = opts;
+    if (!config.enabled)
+        return { ok: true };
+    const honeypotField = config.honeypotField || DEFAULT_HONEYPOT_FIELD;
+    const honeypotValue = body[honeypotField];
+    if (typeof honeypotValue === 'string' && honeypotValue.trim() !== '') {
+        return { ok: false, softOk: true, fakeText: 'Gracias. Te responderemos pronto.' };
+    }
+    const fields = validateContactFields({
+        email: body.email,
+        message: body.message ?? body.text,
+        maxMessageChars: config.maxMessageChars || DEFAULT_CONTACT_MAX_MESSAGE_CHARS,
+    });
+    if (!fields.ok)
+        return { ok: false, status: 400, error: fields.error };
+    const ticket = typeof body.contactTicket === 'string'
+        ? body.contactTicket
+        : typeof body.ticket === 'string'
+            ? body.ticket
+            : undefined;
+    const ticketCheck = verifyContactTicket(ticket, ticketSecret, {
+        minAgeMs: config.minSubmitAgeMs ?? DEFAULT_CONTACT_MIN_AGE_MS,
+        maxAgeMs: config.maxSubmitAgeMs ?? DEFAULT_CONTACT_MAX_AGE_MS,
+    });
+    if (!ticketCheck.ok)
+        return { ok: false, status: 403, error: ticketCheck.error };
+    const ip = clientIpFromRequest(request);
+    const rateKey = `contact:${visitorId}:${ip || 'noip'}`;
+    const rate = checkContactRateLimit(rateKey, config.maxPerHour ?? DEFAULT_CONTACT_MAX_PER_HOUR);
+    if (!rate.ok) {
+        return { ok: false, status: 429, error: rate.error, retryAfterSec: rate.retryAfterSec };
+    }
+    const needsCaptcha = Boolean(config.recaptchaSecret) && config.requireRecaptcha !== false;
+    if (needsCaptcha) {
+        const token = typeof body.captchaToken === 'string'
+            ? body.captchaToken
+            : typeof body.recaptchaToken === 'string'
+                ? body.recaptchaToken
+                : '';
+        const captcha = await verifyRecaptchaV3({
+            secret: config.recaptchaSecret,
+            token,
+            minScore: config.recaptchaMinScore ?? DEFAULT_RECAPTCHA_MIN_SCORE,
+            expectedAction: config.recaptchaAction || DEFAULT_RECAPTCHA_ACTION,
+            remoteIp: ip,
+        });
+        if (!captcha.ok)
+            return { ok: false, status: 403, error: captcha.error };
+    }
+    return { ok: true };
+}

package/dist/server/index.d.ts

@@ -1,3 +1,4 @@
 export { createSocialProxy, socialProxyRoute } from './proxy';
 export { attachSocialWebSocket, buildWsEnvelope } from './websocket';
 export { resolveVisitorId, parseCookies, DEFAULT_COOKIE_NAME } from './visitorCookie';
+export { resolveAntiSpamConfig, issueContactTicket, verifyContactTicket, verifyRecaptchaV3, enforceContactAntiSpam, resetContactRateLimits, DEFAULT_HONEYPOT_FIELD, DEFAULT_RECAPTCHA_ACTION, } from './antiSpam';

package/dist/server/index.js

@@ -1,13 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_COOKIE_NAME = exports.parseCookies = exports.resolveVisitorId = exports.buildWsEnvelope = exports.attachSocialWebSocket = exports.socialProxyRoute = exports.createSocialProxy = void 0;
-var proxy_1 = require("./proxy");
-Object.defineProperty(exports, "createSocialProxy", { enumerable: true, get: function () { return proxy_1.createSocialProxy; } });
-Object.defineProperty(exports, "socialProxyRoute", { enumerable: true, get: function () { return proxy_1.socialProxyRoute; } });
-var websocket_1 = require("./websocket");
-Object.defineProperty(exports, "attachSocialWebSocket", { enumerable: true, get: function () { return websocket_1.attachSocialWebSocket; } });
-Object.defineProperty(exports, "buildWsEnvelope", { enumerable: true, get: function () { return websocket_1.buildWsEnvelope; } });
-var visitorCookie_1 = require("./visitorCookie");
-Object.defineProperty(exports, "resolveVisitorId", { enumerable: true, get: function () { return visitorCookie_1.resolveVisitorId; } });
-Object.defineProperty(exports, "parseCookies", { enumerable: true, get: function () { return visitorCookie_1.parseCookies; } });
-Object.defineProperty(exports, "DEFAULT_COOKIE_NAME", { enumerable: true, get: function () { return visitorCookie_1.DEFAULT_COOKIE_NAME; } });
+export { createSocialProxy, socialProxyRoute } from './proxy';
+export { attachSocialWebSocket, buildWsEnvelope } from './websocket';
+export { resolveVisitorId, parseCookies, DEFAULT_COOKIE_NAME } from './visitorCookie';
+export { resolveAntiSpamConfig, issueContactTicket, verifyContactTicket, verifyRecaptchaV3, enforceContactAntiSpam, resetContactRateLimits, DEFAULT_HONEYPOT_FIELD, DEFAULT_RECAPTCHA_ACTION, } from './antiSpam';

package/dist/server/proxy.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSocialProxy = createSocialProxy;
-exports.socialProxyRoute = socialProxyRoute;
-const crypto_1 = require("../crypto");
-const visitorCookie_1 = require("./visitorCookie");
+import { signHmacHex } from '../crypto';
+import { resolveVisitorId, DEFAULT_COOKIE_NAME } from './visitorCookie';
+import { enforceContactAntiSpam, issueContactTicket, resolveAntiSpamConfig, } from './antiSpam';
 function envConfig(partial) {
     const webhookUrl = partial?.webhookUrl || process.env.URANO_SOCIAL_WEBHOOK_URL || '';
     const webhookSecret = partial?.webhookSecret || process.env.URANO_SOCIAL_WEBHOOK_SECRET || '';
@@ -15,9 +12,10 @@ function envConfig(partial) {
         webhookUrl: webhookUrl.replace(/\/$/, ''),
         webhookSecret,
         cookieSecret: partial?.cookieSecret || process.env.URANO_SOCIAL_COOKIE_SECRET || webhookSecret,
-        cookieName: partial?.cookieName || visitorCookie_1.DEFAULT_COOKIE_NAME,
+        cookieName: partial?.cookieName || DEFAULT_COOKIE_NAME,
         cookieMaxAgeSec: partial?.cookieMaxAgeSec,
         defaultDisplayName: partial?.defaultDisplayName,
+        antiSpam: resolveAntiSpamConfig(partial?.antiSpam),
     };
 }
 function json(status, body, headers) {
@@ -41,8 +39,9 @@ async function readJson(request) {
  * Creates a site-local proxy that signs webhook traffic with the server secret.
  * The browser never receives WEBHOOK_SECRET.
  */
-function createSocialProxy(partial) {
+export function createSocialProxy(partial) {
     const config = envConfig(partial);
+    const antiSpam = resolveAntiSpamConfig(config.antiSpam);
     async function handle(request) {
         const url = new URL(request.url);
         const method = request.method.toUpperCase();
@@ -57,7 +56,7 @@ function createSocialProxy(partial) {
                 },
             });
         }
-        const visitor = (0, visitorCookie_1.resolveVisitorId)({
+        const visitor = resolveVisitorId({
             cookieHeader: request.headers.get('cookie'),
             cookieName: config.cookieName,
             cookieSecret: config.cookieSecret,
@@ -65,7 +64,20 @@ function createSocialProxy(partial) {
         const responseHeaders = new Headers();
         if (visitor.setCookie)
             responseHeaders.append('Set-Cookie', visitor.setCookie);
-        if (method === 'GET' && !url.searchParams.get('mode') && !url.searchParams.get('payload')) {
+        const action = url.searchParams.get('action');
+        if (method === 'GET' && action === 'contact-ticket') {
+            const ticket = issueContactTicket(config.cookieSecret || config.webhookSecret);
+            return json(200, {
+                ok: true,
+                ticket,
+                minAgeMs: antiSpam.minSubmitAgeMs,
+                maxAgeMs: antiSpam.maxSubmitAgeMs,
+                honeypotField: antiSpam.honeypotField,
+                recaptchaRequired: Boolean(antiSpam.recaptchaSecret) && antiSpam.requireRecaptcha !== false,
+                recaptchaAction: antiSpam.recaptchaAction,
+            }, responseHeaders);
+        }
+        if (method === 'GET' && !url.searchParams.get('mode') && !url.searchParams.get('payload') && !action) {
             try {
                 const discovery = await fetch(config.webhookUrl, { method: 'GET' });
                 const body = await discovery.json().catch(() => ({ ok: discovery.ok }));
@@ -74,6 +86,15 @@ function createSocialProxy(partial) {
                     ok: true,
                     proxy: true,
                     visitorId: visitor.visitorId,
+                    antiSpam: {
+                        enabled: antiSpam.enabled !== false,
+                        honeypotField: antiSpam.honeypotField,
+                        ticket: true,
+                        rateLimitPerHour: antiSpam.maxPerHour,
+                        recaptcha: Boolean(antiSpam.recaptchaSecret),
+                        recaptchaRequired: Boolean(antiSpam.recaptchaSecret) && antiSpam.requireRecaptcha !== false,
+                        recaptchaAction: antiSpam.recaptchaAction,
+                    },
                     upstream: body,
                 }), { status: 200, headers: responseHeaders });
             }
@@ -98,6 +119,31 @@ function createSocialProxy(partial) {
             || clientBody.mode
             || ((request.headers.get('Accept') || '').includes('text/event-stream') ? 'sse' : 'wait'));
         const isContact = ['contact', 'email', 'form'].includes(String(clientBody.type || clientBody.channel || '').toLowerCase());
+        if (isContact) {
+            const gate = await enforceContactAntiSpam({
+                body: clientBody,
+                request,
+                visitorId: visitor.visitorId,
+                ticketSecret: config.cookieSecret || config.webhookSecret,
+                config: antiSpam,
+            });
+            if (!gate.ok) {
+                if ('softOk' in gate && gate.softOk) {
+                    return json(200, {
+                        ok: true,
+                        channel: 'contact',
+                        delivered: 'honeypot',
+                        text: gate.fakeText,
+                    }, responseHeaders);
+                }
+                if ('status' in gate) {
+                    if (gate.retryAfterSec)
+                        responseHeaders.set('Retry-After', String(gate.retryAfterSec));
+                    return json(gate.status, { error: gate.error, retryAfterSec: gate.retryAfterSec }, responseHeaders);
+                }
+                return json(403, { error: 'contact_rejected' }, responseHeaders);
+            }
+        }
         const outbound = isContact
             ? { type: 'contact' }
             : {
@@ -146,7 +192,7 @@ function createSocialProxy(partial) {
         delete clientBody.visitorId;
         delete clientBody.from;
         const rawBody = JSON.stringify(outbound);
-        const signature = (0, crypto_1.signHmacHex)(rawBody, config.webhookSecret);
+        const signature = signHmacHex(rawBody, config.webhookSecret);
         const idempotency = request.headers.get('Idempotency-Key')
             || (typeof outbound.idempotencyKey === 'string' ? outbound.idempotencyKey : undefined);
         const upstreamHeaders = {
@@ -197,7 +243,7 @@ function createSocialProxy(partial) {
     return { handle };
 }
 /** Convenience for Next.js App Router route handlers. */
-function socialProxyRoute(partial) {
+export function socialProxyRoute(partial) {
     const proxy = createSocialProxy(partial);
     return {
         GET: (request) => proxy.handle(request),

package/dist/server/visitorCookie.js

@@ -1,11 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_COOKIE_NAME = void 0;
-exports.parseCookies = parseCookies;
-exports.resolveVisitorId = resolveVisitorId;
-const crypto_1 = require("../crypto");
-exports.DEFAULT_COOKIE_NAME = 'urano_social_vid';
-function parseCookies(header) {
+import { randomId, signCookieValue, verifyCookieValue } from '../crypto';
+export const DEFAULT_COOKIE_NAME = 'urano_social_vid';
+export function parseCookies(header) {
     const out = {};
     if (!header)
         return out;
@@ -20,17 +15,17 @@ function parseCookies(header) {
     }
     return out;
 }
-function resolveVisitorId(opts) {
-    const name = opts.cookieName || exports.DEFAULT_COOKIE_NAME;
+export function resolveVisitorId(opts) {
+    const name = opts.cookieName || DEFAULT_COOKIE_NAME;
     const cookies = parseCookies(opts.cookieHeader);
     const existing = cookies[name];
     if (existing) {
-        const verified = (0, crypto_1.verifyCookieValue)(existing, opts.cookieSecret);
+        const verified = verifyCookieValue(existing, opts.cookieSecret);
         if (verified)
             return { visitorId: verified, isNew: false };
     }
-    const visitorId = (0, crypto_1.randomId)('vis');
-    const signed = (0, crypto_1.signCookieValue)(visitorId, opts.cookieSecret);
+    const visitorId = randomId('vis');
+    const signed = signCookieValue(visitorId, opts.cookieSecret);
     const maxAge = 60 * 60 * 24 * 365;
     const setCookie = [
         `${name}=${encodeURIComponent(signed)}`,

package/dist/server/websocket.js

@@ -1,19 +1,15 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.attachSocialWebSocket = attachSocialWebSocket;
-exports.buildWsEnvelope = buildWsEnvelope;
-const crypto_1 = require("../crypto");
-const visitorCookie_1 = require("./visitorCookie");
+import { signHmacHex } from '../crypto';
+import { resolveVisitorId, DEFAULT_COOKIE_NAME } from './visitorCookie';
 /**
  * Attaches an optional WebSocket bridge to a Node HTTP server.
  * Next App Router cannot upgrade sockets in a route handler — use SSE there.
  * Astro Node / custom servers can call this after `http.createServer`.
  */
-function attachSocialWebSocket(server, partial) {
+export function attachSocialWebSocket(server, partial) {
     const webhookUrl = (partial?.webhookUrl || process.env.URANO_SOCIAL_WEBHOOK_URL || '').replace(/\/$/, '');
     const webhookSecret = partial?.webhookSecret || process.env.URANO_SOCIAL_WEBHOOK_SECRET || '';
     const cookieSecret = partial?.cookieSecret || process.env.URANO_SOCIAL_COOKIE_SECRET || webhookSecret;
-    const cookieName = partial?.cookieName || visitorCookie_1.DEFAULT_COOKIE_NAME;
+    const cookieName = partial?.cookieName || DEFAULT_COOKIE_NAME;
     const path = partial?.path || '/api/urano-social/ws';
     if (!webhookUrl || !webhookSecret) {
         throw new Error('attachSocialWebSocket requires URANO_SOCIAL_WEBHOOK_URL and URANO_SOCIAL_WEBHOOK_SECRET');
@@ -23,7 +19,7 @@ function attachSocialWebSocket(server, partial) {
         const url = new URL(req.url || '/', 'http://localhost');
         if (url.pathname !== path)
             return;
-        const visitor = (0, visitorCookie_1.resolveVisitorId)({
+        const visitor = resolveVisitorId({
             cookieHeader: req.headers.cookie,
             cookieName,
             cookieSecret,
@@ -68,7 +64,7 @@ function attachSocialWebSocket(server, partial) {
                     turnId: msg.turnId,
                 };
                 const payloadStr = JSON.stringify(payloadObj);
-                const signature = (0, crypto_1.signHmacHex)(payloadStr, webhookSecret);
+                const signature = signHmacHex(payloadStr, webhookSecret);
                 upstream.send(JSON.stringify({
                     payload: payloadStr,
                     headers: {
@@ -117,12 +113,12 @@ function attachSocialWebSocket(server, partial) {
     return () => server.off('upgrade', onUpgrade);
 }
 /** Exported for tests — builds the WS envelope the upstream expects. */
-function buildWsEnvelope(payload, secret) {
+export function buildWsEnvelope(payload, secret) {
     const payloadStr = JSON.stringify(payload);
     return {
         payload: payloadStr,
         headers: {
-            'x-urano-signature': (0, crypto_1.signHmacHex)(payloadStr, secret),
+            'x-urano-signature': signHmacHex(payloadStr, secret),
             'Content-Type': 'application/json',
             'X-Urano-Protocol-Version': '1',
         },

package/dist/types.d.ts

@@ -1,5 +1,33 @@
 export type SocialTransport = 'sse' | 'wait' | 'ws' | 'async';
 export type WebhookAction = 'status' | 'events' | 'cancel';
+/** Shared honeypot field name (safe to import from browser bundles). */
+export declare const DEFAULT_HONEYPOT_FIELD = "website";
+export declare const DEFAULT_RECAPTCHA_ACTION = "contact";
+export interface ContactAntiSpamConfig {
+    /** Master switch for contact gates. Default true. */
+    enabled?: boolean;
+    /** Hidden field name bots fill. Default `website`. */
+    honeypotField?: string;
+    /** Minimum ms between issuing a contact ticket and accepting submit. Default 2500. */
+    minSubmitAgeMs?: number;
+    /** Maximum ticket lifetime. Default 30 minutes. */
+    maxSubmitAgeMs?: number;
+    /** Max contact submits per visitor+IP per hour. Default 5. */
+    maxPerHour?: number;
+    /** Max message length. Default 4000. */
+    maxMessageChars?: number;
+    /** Google reCAPTCHA v3 secret (server-only). Env: URANO_SOCIAL_RECAPTCHA_SECRET */
+    recaptchaSecret?: string;
+    /** Minimum v3 score. Default 0.5. */
+    recaptchaMinScore?: number;
+    /** Expected grecaptcha action. Default `contact`. */
+    recaptchaAction?: string;
+    /**
+     * When a recaptcha secret is set, require a token (default true).
+     * Set false to verify only when the client sends a token.
+     */
+    requireRecaptcha?: boolean;
+}
 export interface SocialProxyConfig {
     webhookUrl: string;
     webhookSecret: string;
@@ -9,6 +37,8 @@ export interface SocialProxyConfig {
     cookieMaxAgeSec?: number;
     /** Default display name forwarded as displayName when the client omits one. */
     defaultDisplayName?: string;
+    /** Contact-form anti-spam (honeypot, ticket, rate limit, optional reCAPTCHA v3). */
+    antiSpam?: ContactAntiSpamConfig;
 }
 export interface SocialClientMessage {
     id: string;

package/dist/types.js

@@ -1,2 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+/** Shared honeypot field name (safe to import from browser bundles). */
+export const DEFAULT_HONEYPOT_FIELD = 'website';
+export const DEFAULT_RECAPTCHA_ACTION = 'contact';

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@uranotools/urano-social",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Customer-support chat widget for SalesAgentConnector MCP webhooks (SSE / WebSocket / wait)",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {