@webpresso/forms 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @webpresso/forms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Contact-form submission handling for Workers: field validation and sanitization, captcha gating, internal + confirmation email dispatch, and redirect responses with a status vocabulary. Provider-neutral root surface; the captcha vendor is confined to a single adapter subpath.
+
+## Install
+
+```bash
+vp add @webpresso/forms
+```
+
+The public package names and release policy are defined by `.webpresso/package-surface.json` in the framework repository.
+
+## Config shape
+
+```ts
+import type { ContactFormConfig } from '@webpresso/forms'
+
+const config: ContactFormConfig = {
+  siteName: 'Example',
+  from: 'no-reply@example.com',
+  internalRecipients: ['team@example.com'],
+  fields: [
+    { name: 'name', label: 'Name', type: 'text', required: true },
+    { name: 'email', label: 'Email', type: 'email', required: true },
+    { name: 'message', label: 'Message', type: 'textarea', required: true },
+  ],
+  customerEmailField: 'email',
+  customerNameField: 'name',
+  redirectPath: '/contact',
+  subjects: { internal: 'New contact request', confirmation: 'We received your message' },
+}
+```
+
+Field types are `text | email | textarea | tel`; values are control-character-stripped, whitespace-collapsed, length-capped (`maxLength`, default 2000), and email-typed fields are lowercased. Required fields and the customer email field are validated before any email is sent.
+
+## Usage
+
+Mount the handler in a Worker with an email binding and a captcha verifier:
+
+```ts
+import { createContactFormHandler } from '@webpresso/forms'
+import { createTurnstileVerifier } from '@webpresso/forms/adapters/turnstile'
+
+const contact = createContactFormHandler(config, {
+  captcha: createTurnstileVerifier({ secret: env.TURNSTILE_SECRET }),
+})
+
+export default {
+  fetch: (request, env) => {
+    const url = new URL(request.url)
+    if (url.pathname === '/api/contact' && request.method === 'POST') {
+      return contact(request, { email: env.SEND_EMAIL })
+    }
+    return new Response('Not found', { status: 404 })
+  },
+}
+```
+
+`context.email` is an `EmailBinding` (`send(message)`); when it is absent the handler redirects with the `email` status instead of sending. A custom `CaptchaVerifier` can replace the adapter at the neutral `captcha` option.
+
+## Redirect status vocabulary
+
+The handler answers with a `303` redirect to the form path (or the form's hidden `redirect` field when present) carrying a `contact` query parameter:
+
+| Value     | Meaning                                       |
+| --------- | --------------------------------------------- |
+| `success` | Validation, captcha, and both emails accepted |
+| `invalid` | Wrong method, unparsable form, or bad fields  |
+| `captcha` | Captcha failed or the verifier errored        |
+| `email`   | No email binding, or the internal send failed |
+
+The confirmation email is best-effort: its failure is logged, never fails the request.
+
+## Adapter-confined naming
+
+The root surface stays provider-neutral: vendor names appear only where the adapter subpath is documented. `@webpresso/forms/adapters/turnstile` is the single subpath naming the captcha vendor, its siteverify endpoint, and its form field name — mirroring how the runtime documents its auth adapter imports. Import the adapter explicitly; nothing vendor-specific is re-exported from the root.
+
+## Provenance
+
+Logic ported from the in-org public `ozby/cloudflare-utils` repository, pinned at commit `dd4cb995c8b786f30b5b2993cd40b05e2a73bb56`. The source repository carries no LICENSE file and the module is authored in-org by the rights holder, so this port is licensed Elastic-2.0 as part of the framework inventory.
+
+## License
+
+Elastic-2.0

package/dist/adapters/turnstile.d.ts

@@ -0,0 +1,5 @@
+import { type CaptchaVerifier } from '../contact-form.js';
+export declare function createTurnstileVerifier(options: {
+    readonly secret: string;
+    readonly fetcher?: typeof fetch;
+}): CaptchaVerifier;

package/dist/adapters/turnstile.js

@@ -0,0 +1,40 @@
+import { sanitizeContactValue } from '../contact-form.js';
+// Vendor-confined constants: the Turnstile siteverify endpoint and form field
+// name appear nowhere else in the package — the root surface stays
+// provider-neutral.
+const SITEVERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+const TOKEN_FIELD = 'cf-turnstile-response';
+function errorCodes(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'string');
+}
+export function createTurnstileVerifier(options) {
+    const fetcher = options.fetcher ?? fetch;
+    return {
+        async verify({ request, data }) {
+            const token = sanitizeContactValue(data.get(TOKEN_FIELD));
+            if (options.secret.length === 0 || token.length === 0) {
+                return { ok: false, codes: ['missing-input'] };
+            }
+            try {
+                const body = { secret: options.secret, response: token };
+                const remoteIp = request.headers.get('CF-Connecting-IP') ?? request.headers.get('X-Forwarded-For');
+                if (remoteIp != null && remoteIp.length > 0)
+                    body.remoteip = remoteIp;
+                const response = await fetcher(SITEVERIFY_URL, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify(body),
+                });
+                const result = (await response.json());
+                if (result.success === true)
+                    return { ok: true };
+                return { ok: false, codes: errorCodes(result['error-codes']) };
+            }
+            catch {
+                return { ok: false, codes: ['internal-error'] };
+            }
+        },
+    };
+}

package/dist/contact-form.d.ts

@@ -0,0 +1,73 @@
+export type ContactFieldType = 'text' | 'email' | 'textarea' | 'tel';
+export type ContactFieldConfig = {
+    readonly name: string;
+    readonly label: string;
+    readonly required?: boolean;
+    readonly type?: ContactFieldType;
+    readonly maxLength?: number;
+};
+export type EmailAddress = string | {
+    email: string;
+    name?: string;
+};
+export type EmailMessageBuilder = {
+    readonly to: EmailAddress | readonly EmailAddress[];
+    readonly from: EmailAddress;
+    readonly subject: string;
+    readonly html?: string;
+    readonly text?: string;
+    readonly cc?: EmailAddress | readonly EmailAddress[];
+    readonly bcc?: EmailAddress | readonly EmailAddress[];
+    readonly replyTo?: EmailAddress;
+    readonly headers?: Record<string, string>;
+};
+export type EmailBinding = {
+    send(message: EmailMessageBuilder): Promise<unknown>;
+};
+export type ContactFormContext = {
+    readonly email?: EmailBinding;
+};
+export type ContactFormConfig = {
+    readonly siteName: string;
+    readonly from: string;
+    readonly internalRecipients: readonly string[];
+    readonly fields: readonly ContactFieldConfig[];
+    readonly customerEmailField: string;
+    readonly customerNameField?: string;
+    readonly redirectPath: string;
+    readonly subjects: {
+        readonly internal: string;
+        readonly confirmation: string;
+    };
+    readonly internalIntro?: string;
+    readonly confirmationText?: (values: Record<string, string>) => string;
+};
+export type ContactValidationResult = {
+    readonly ok: true;
+    readonly values: Record<string, string>;
+} | {
+    readonly ok: false;
+    readonly error: 'invalid_fields';
+    readonly fields: readonly string[];
+};
+export type CaptchaVerification = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly codes: readonly string[];
+};
+export type CaptchaVerifier = {
+    verify(input: {
+        readonly request: Request;
+        readonly data: FormData;
+    }): Promise<CaptchaVerification>;
+};
+export type ContactFormHandlerOptions = {
+    readonly captcha: CaptchaVerifier;
+    readonly logger?: Pick<Console, 'warn'>;
+};
+export declare function sanitizeContactValue(value: FormDataEntryValue | null, field?: ContactFieldConfig): string;
+export declare function validateContactForm(config: ContactFormConfig, data: FormData): ContactValidationResult;
+export declare function buildInternalContactEmail(config: ContactFormConfig, values: Record<string, string>): EmailMessageBuilder;
+export declare function buildContactConfirmationEmail(config: ContactFormConfig, values: Record<string, string>): EmailMessageBuilder;
+export declare function createContactFormHandler(config: ContactFormConfig, options: ContactFormHandlerOptions): (request: Request, context: ContactFormContext) => Promise<Response>;

package/dist/contact-form.js

@@ -0,0 +1,186 @@
+const DEFAULT_MAX_LENGTH = 2_000;
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/u;
+// Strip C0 controls (keeping \t and \n) plus DEL by codepoint, not by a regex
+// literal: `no-control-regex` rejects the literal form outright, and the
+// behaviour is identical — tab and newline survive for whitespace handling.
+const CONTROL_FREE_PATTERN = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(8)}${String.fromCharCode(11)}${String.fromCharCode(12)}${String.fromCharCode(14)}-${String.fromCharCode(31)}${String.fromCharCode(127)}]`, 'gu');
+function collapseInlineWhitespace(value) {
+    return value.replace(/[\t ]+/gu, ' ');
+}
+export function sanitizeContactValue(value, field) {
+    if (typeof value !== 'string')
+        return '';
+    const withoutControls = value.replace(CONTROL_FREE_PATTERN, '');
+    const normalized = field?.type === 'textarea'
+        ? withoutControls
+            .replace(/\r\n?/gu, '\n')
+            .split('\n')
+            .map((line) => collapseInlineWhitespace(line).trim())
+            .join('\n')
+        : collapseInlineWhitespace(withoutControls.replace(/[\r\n]+/gu, ' '));
+    const trimmed = normalized.trim();
+    const capped = trimmed.slice(0, field?.maxLength ?? DEFAULT_MAX_LENGTH);
+    return field?.type === 'email' ? capped.toLowerCase() : capped;
+}
+export function validateContactForm(config, data) {
+    const invalid = [];
+    const values = {};
+    for (const field of config.fields) {
+        const value = sanitizeContactValue(data.get(field.name), field);
+        values[field.name] = value;
+        if (field.required === true && value.length === 0)
+            invalid.push(field.name);
+        if (field.type === 'email' && value.length > 0 && !EMAIL_PATTERN.test(value))
+            invalid.push(field.name);
+    }
+    const customerEmail = values[config.customerEmailField] ?? '';
+    if (customerEmail.length === 0 || !EMAIL_PATTERN.test(customerEmail)) {
+        if (!invalid.includes(config.customerEmailField))
+            invalid.push(config.customerEmailField);
+    }
+    return invalid.length > 0
+        ? { ok: false, error: 'invalid_fields', fields: invalid }
+        : { ok: true, values };
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/gu, '&')
+        .replace(/</gu, '&lt;')
+        .replace(/>/gu, '&gt;')
+        .replace(/"/gu, '&quot;')
+        .replace(/'/gu, '&#39;');
+}
+function fieldText(config, values) {
+    return config.fields.map((field) => `${field.label}: ${values[field.name] ?? ''}`).join('\n');
+}
+export function buildInternalContactEmail(config, values) {
+    const intro = config.internalIntro ?? `New contact form submission from ${config.siteName}.`;
+    const rows = config.fields
+        .map((field) => `<tr><th align="left" valign="top">${escapeHtml(field.label)}</th><td>${escapeHtml(values[field.name] ?? '').replace(/\n/gu, '<br>')}</td></tr>`)
+        .join('');
+    return {
+        to: [...config.internalRecipients],
+        from: config.from,
+        replyTo: values[config.customerEmailField],
+        subject: config.subjects.internal,
+        text: `${intro}\n\n${fieldText(config, values)}`,
+        html: `<p>${escapeHtml(intro)}</p><table>${rows}</table>`,
+    };
+}
+export function buildContactConfirmationEmail(config, values) {
+    const customerName = config.customerNameField ? values[config.customerNameField] : '';
+    const greeting = customerName ? `Hi ${customerName},` : 'Hello,';
+    const text = config.confirmationText?.(values) ??
+        [
+            greeting,
+            '',
+            `We received your message to ${config.siteName}.`,
+            'We will review it and reply as soon as possible.',
+        ].join('\n');
+    return {
+        to: values[config.customerEmailField] ?? '',
+        from: config.from,
+        replyTo: config.from,
+        subject: config.subjects.confirmation,
+        text,
+        html: `<p>${escapeHtml(greeting)}</p><p>We received your message to ${escapeHtml(config.siteName)}. We will review it and reply as soon as possible.</p>`,
+    };
+}
+function redirectWithStatus(path, status) {
+    const url = new URL(path, 'https://local.invalid');
+    url.searchParams.set('contact', status);
+    return new Response(null, {
+        status: 303,
+        headers: { location: `${url.pathname}${url.search}${url.hash}` },
+    });
+}
+/**
+ * Decides whether a decoded `_redirect` value is safe to send back as a
+ * `Location` target. Hardened beyond the source (which accepted any value
+ * starting with `/` and not `//`):
+ *
+ * - The value must start with `/` and its second character must be neither
+ *   `/` nor `\`. The WHATWG URL parser reads `/\` as `//`, so `/\evil.com`
+ *   would otherwise parse as a protocol-relative reference to evil.com.
+ * - The value must contain no `\` and no control character (U+0000-U+001F or
+ *   U+007F) anywhere. The WHATWG URL parser strips tab/LF/CR before parsing,
+ *   so a decoded value carrying a literal tab or LF next to a slash can
+ *   re-form a protocol-relative reference.
+ *
+ * The check runs on the raw decoded field value: whitespace normalization in
+ * `sanitizeContactValue` would erase the control bytes before they could be
+ * rejected. Any rejected target falls back to `config.redirectPath`.
+ */
+function isSafeRedirectTarget(target) {
+    if (!target.startsWith('/'))
+        return false;
+    const second = target.charCodeAt(1);
+    if (second === 0x2f /* / */ || second === 0x5c /* \ */)
+        return false;
+    for (let index = 0; index < target.length; index++) {
+        const code = target.charCodeAt(index);
+        if (code === 0x5c /* \ */)
+            return false;
+        if (code <= 0x1f || code === 0x7f)
+            return false;
+    }
+    return true;
+}
+function redirectTarget(config, data) {
+    const raw = data.get('_redirect');
+    if (typeof raw === 'string' && isSafeRedirectTarget(raw))
+        return sanitizeContactValue(raw);
+    return config.redirectPath;
+}
+function errorCode(error) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string')
+        return error.code;
+    return 'unknown';
+}
+export function createContactFormHandler(config, options) {
+    return async (request, context) => {
+        if (request.method !== 'POST')
+            return redirectWithStatus(config.redirectPath, 'invalid');
+        let data;
+        try {
+            data = await request.formData();
+        }
+        catch {
+            return redirectWithStatus(config.redirectPath, 'invalid');
+        }
+        const target = redirectTarget(config, data);
+        const validation = validateContactForm(config, data);
+        if (!validation.ok)
+            return redirectWithStatus(target, 'invalid');
+        let verification;
+        try {
+            verification = await options.captcha.verify({ request, data });
+        }
+        catch {
+            return redirectWithStatus(target, 'captcha');
+        }
+        if (!verification.ok)
+            return redirectWithStatus(target, 'captcha');
+        if (context.email == null)
+            return redirectWithStatus(target, 'email');
+        try {
+            await context.email.send(buildInternalContactEmail(config, validation.values));
+        }
+        catch {
+            return redirectWithStatus(target, 'email');
+        }
+        try {
+            await context.email.send(buildContactConfirmationEmail(config, validation.values));
+        }
+        catch (error) {
+            options.logger?.warn('contact_confirmation_failed', {
+                code: errorCode(error),
+                site: config.siteName,
+            });
+        }
+        return redirectWithStatus(target, 'success');
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './contact-form.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './contact-form.js';

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@webpresso/forms",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Webpresso drop-in form components: a provider-neutral contact-form handler for edge workers.",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webpresso/framework.git",
+    "directory": "packages/forms"
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./adapters/turnstile": {
+      "types": "./dist/adapters/turnstile.d.ts",
+      "default": "./dist/adapters/turnstile.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && add-js-extensions dist",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint:pkg": "publint --pack false",
+    "prepublishOnly": "wp run build && wp run lint:pkg"
+  },
+  "devDependencies": {
+    "@mergifyio/vitest": "catalog:",
+    "@repo/build-tools": "workspace:*",
+    "@types/node": "catalog:",
+    "@webpresso/app-config": "catalog:",
+    "publint": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}