@uranotools/urano-social 0.0.0-stage → 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

@@ -0,0 +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

@@ -0,0 +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/proxy.d.ts

@@ -0,0 +1,16 @@
+import type { SocialProxyConfig } from '../types';
+export interface SocialProxyHandlers {
+    /** Fetch/Web-standard handler for App Router / Astro / edge-compatible hosts. */
+    handle: (request: Request) => Promise<Response>;
+}
+/**
+ * Creates a site-local proxy that signs webhook traffic with the server secret.
+ * The browser never receives WEBHOOK_SECRET.
+ */
+export declare function createSocialProxy(partial?: Partial<SocialProxyConfig>): SocialProxyHandlers;
+/** Convenience for Next.js App Router route handlers. */
+export declare function socialProxyRoute(partial?: Partial<SocialProxyConfig>): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+    OPTIONS: (request: Request) => Promise<Response>;
+};

package/dist/server/proxy.js

@@ -0,0 +1,253 @@
+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 || '';
+    if (!webhookUrl)
+        throw new Error('URANO_SOCIAL_WEBHOOK_URL is required');
+    if (!webhookSecret)
+        throw new Error('URANO_SOCIAL_WEBHOOK_SECRET is required');
+    return {
+        webhookUrl: webhookUrl.replace(/\/$/, ''),
+        webhookSecret,
+        cookieSecret: partial?.cookieSecret || process.env.URANO_SOCIAL_COOKIE_SECRET || webhookSecret,
+        cookieName: partial?.cookieName || DEFAULT_COOKIE_NAME,
+        cookieMaxAgeSec: partial?.cookieMaxAgeSec,
+        defaultDisplayName: partial?.defaultDisplayName,
+        antiSpam: resolveAntiSpamConfig(partial?.antiSpam),
+    };
+}
+function json(status, body, headers) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'Content-Type': 'application/json', ...(headers || {}) },
+    });
+}
+async function readJson(request) {
+    const text = await request.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('invalid_json');
+    }
+}
+/**
+ * Creates a site-local proxy that signs webhook traffic with the server secret.
+ * The browser never receives WEBHOOK_SECRET.
+ */
+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();
+        if (method === 'OPTIONS') {
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    'Access-Control-Allow-Origin': request.headers.get('Origin') || '*',
+                    'Access-Control-Allow-Methods': 'GET,POST,OPTIONS',
+                    'Access-Control-Allow-Headers': 'Content-Type, Idempotency-Key, Last-Event-ID, Accept',
+                    'Access-Control-Allow-Credentials': 'true',
+                },
+            });
+        }
+        const visitor = resolveVisitorId({
+            cookieHeader: request.headers.get('cookie'),
+            cookieName: config.cookieName,
+            cookieSecret: config.cookieSecret,
+        });
+        const responseHeaders = new Headers();
+        if (visitor.setCookie)
+            responseHeaders.append('Set-Cookie', visitor.setCookie);
+        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 }));
+                responseHeaders.set('Content-Type', 'application/json');
+                return new Response(JSON.stringify({
+                    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 });
+            }
+            catch (error) {
+                return json(502, { error: 'upstream_unreachable', message: error?.message }, responseHeaders);
+            }
+        }
+        let clientBody = {};
+        try {
+            if (method === 'GET') {
+                const payloadParam = url.searchParams.get('payload');
+                clientBody = payloadParam ? JSON.parse(payloadParam) : {};
+            }
+            else {
+                clientBody = await readJson(request);
+            }
+        }
+        catch {
+            return json(400, { error: 'invalid_json' }, responseHeaders);
+        }
+        const mode = String(url.searchParams.get('mode')
+            || 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' }
+            : {
+                visitorId: visitor.visitorId,
+                from: visitor.visitorId,
+            };
+        if (isContact) {
+            if (typeof clientBody.email === 'string')
+                outbound.email = clientBody.email.trim().toLowerCase();
+            if (typeof clientBody.name === 'string')
+                outbound.name = clientBody.name;
+            if (typeof clientBody.subject === 'string')
+                outbound.subject = clientBody.subject;
+            if (typeof clientBody.message === 'string')
+                outbound.message = clientBody.message;
+            else if (typeof clientBody.text === 'string')
+                outbound.message = clientBody.text;
+            if (typeof clientBody.phone === 'string')
+                outbound.phone = clientBody.phone;
+            if (typeof clientBody.company === 'string')
+                outbound.company = clientBody.company;
+            // Correlate without trusting client visitor identity for CRM email channel.
+            outbound.visitorId = visitor.visitorId;
+        }
+        else {
+            if (typeof clientBody.text === 'string')
+                outbound.text = clientBody.text;
+            if (typeof clientBody.sessionId === 'string')
+                outbound.sessionId = clientBody.sessionId;
+            if (typeof clientBody.SessionId === 'string')
+                outbound.sessionId = clientBody.SessionId;
+            if (typeof clientBody.displayName === 'string')
+                outbound.displayName = clientBody.displayName;
+            else if (config.defaultDisplayName)
+                outbound.displayName = config.defaultDisplayName;
+            if (clientBody.webhookAction)
+                outbound.webhookAction = clientBody.webhookAction;
+            if (clientBody.turnId)
+                outbound.turnId = clientBody.turnId;
+            if (clientBody.after)
+                outbound.after = clientBody.after;
+            if (clientBody.idempotencyKey)
+                outbound.idempotencyKey = clientBody.idempotencyKey;
+        }
+        // Never trust a visitorId / from supplied by the browser for chat identity.
+        delete clientBody.visitorId;
+        delete clientBody.from;
+        const rawBody = JSON.stringify(outbound);
+        const signature = signHmacHex(rawBody, config.webhookSecret);
+        const idempotency = request.headers.get('Idempotency-Key')
+            || (typeof outbound.idempotencyKey === 'string' ? outbound.idempotencyKey : undefined);
+        const upstreamHeaders = {
+            'Content-Type': 'application/json',
+            'x-urano-signature': signature,
+            'X-Urano-Protocol-Version': '1',
+        };
+        if (idempotency)
+            upstreamHeaders['Idempotency-Key'] = idempotency;
+        const lastEventId = request.headers.get('Last-Event-ID');
+        if (lastEventId)
+            upstreamHeaders['Last-Event-ID'] = lastEventId;
+        let upstreamUrl = `${config.webhookUrl}?mode=${encodeURIComponent(mode === 'auto' ? 'sse' : mode)}`;
+        let upstreamInit;
+        if (method === 'GET') {
+            upstreamUrl += `&payload=${encodeURIComponent(rawBody)}`;
+            upstreamInit = { method: 'GET', headers: upstreamHeaders };
+        }
+        else {
+            upstreamInit = { method: 'POST', headers: upstreamHeaders, body: rawBody };
+        }
+        if (mode === 'sse' || request.headers.get('Accept')?.includes('text/event-stream')) {
+            upstreamHeaders['Accept'] = 'text/event-stream';
+        }
+        try {
+            const upstream = await fetch(upstreamUrl, upstreamInit);
+            upstream.headers.forEach((value, key) => {
+                const lower = key.toLowerCase();
+                if (['transfer-encoding', 'content-encoding', 'content-length', 'set-cookie'].includes(lower))
+                    return;
+                responseHeaders.set(key, value);
+            });
+            responseHeaders.set('X-Urano-Social-Visitor', visitor.visitorId);
+            responseHeaders.set('Cache-Control', 'no-cache, no-transform');
+            if (mode === 'sse') {
+                responseHeaders.set('Content-Type', 'text/event-stream; charset=utf-8');
+                responseHeaders.set('X-Accel-Buffering', 'no');
+            }
+            return new Response(upstream.body, {
+                status: upstream.status,
+                headers: responseHeaders,
+            });
+        }
+        catch (error) {
+            return json(502, { error: 'upstream_unreachable', message: error?.message }, responseHeaders);
+        }
+    }
+    return { handle };
+}
+/** Convenience for Next.js App Router route handlers. */
+export function socialProxyRoute(partial) {
+    const proxy = createSocialProxy(partial);
+    return {
+        GET: (request) => proxy.handle(request),
+        POST: (request) => proxy.handle(request),
+        OPTIONS: (request) => proxy.handle(request),
+    };
+}

package/dist/server/visitorCookie.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_COOKIE_NAME = "urano_social_vid";
+export declare function parseCookies(header: string | null | undefined): Record<string, string>;
+export declare function resolveVisitorId(opts: {
+    cookieHeader?: string | null;
+    cookieName?: string;
+    cookieSecret: string;
+}): {
+    visitorId: string;
+    isNew: boolean;
+    setCookie?: string;
+};

package/dist/server/visitorCookie.js

@@ -0,0 +1,38 @@
+import { randomId, signCookieValue, verifyCookieValue } from '../crypto';
+export const DEFAULT_COOKIE_NAME = 'urano_social_vid';
+export function parseCookies(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const part of header.split(';')) {
+        const idx = part.indexOf('=');
+        if (idx < 0)
+            continue;
+        const key = part.slice(0, idx).trim();
+        const value = part.slice(idx + 1).trim();
+        if (key)
+            out[key] = decodeURIComponent(value);
+    }
+    return out;
+}
+export function resolveVisitorId(opts) {
+    const name = opts.cookieName || DEFAULT_COOKIE_NAME;
+    const cookies = parseCookies(opts.cookieHeader);
+    const existing = cookies[name];
+    if (existing) {
+        const verified = verifyCookieValue(existing, opts.cookieSecret);
+        if (verified)
+            return { visitorId: verified, isNew: false };
+    }
+    const visitorId = randomId('vis');
+    const signed = signCookieValue(visitorId, opts.cookieSecret);
+    const maxAge = 60 * 60 * 24 * 365;
+    const setCookie = [
+        `${name}=${encodeURIComponent(signed)}`,
+        'Path=/',
+        `Max-Age=${maxAge}`,
+        'HttpOnly',
+        'SameSite=Lax',
+    ].join('; ');
+    return { visitorId, isNew: true, setCookie };
+}

package/dist/server/websocket.d.ts

@@ -0,0 +1,21 @@
+import * as http from 'http';
+import type { SocialProxyConfig } from '../types';
+export interface AttachSocialWebSocketOptions extends Partial<SocialProxyConfig> {
+    /** Path on the site server that accepts WS upgrades, default `/api/urano-social/ws`. */
+    path?: string;
+}
+/**
+ * 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`.
+ */
+export declare function attachSocialWebSocket(server: http.Server, partial?: AttachSocialWebSocketOptions): () => void;
+/** Exported for tests — builds the WS envelope the upstream expects. */
+export declare function buildWsEnvelope(payload: Record<string, unknown>, secret: string): {
+    payload: string;
+    headers: {
+        'x-urano-signature': string;
+        'Content-Type': string;
+        'X-Urano-Protocol-Version': string;
+    };
+};