@oxygen-agent/cli 1.226.15 → 1.233.8

package/dist/local-custom-http-column.js

@@ -1,5 +1,9 @@
+import { Buffer } from "node:buffer";
+import { isIP } from "node:net";
 import { OxygenError } from "@oxygen/shared";
 import { requestOxygen } from "./http-client.js";
+const LOCAL_CUSTOM_HTTP_TIMEOUT_MS = 10_000;
+const LOCAL_CUSTOM_HTTP_MAX_RESPONSE_BYTES = 1_000_000;
 export async function runLocalCustomHttpColumn(table, columnKeyOrId, options) {
     const described = await requestOxygen("/api/cli/tables/describe", {
         method: "POST",
@@ -17,82 +21,17 @@ export async function runLocalCustomHttpColumn(table, columnKeyOrId, options) {
     });
     const rows = Array.isArray(queried.rows) ? queried.rows.filter(isRecord) : [];
     const concurrency = normalizeLocalConcurrency(options.concurrency);
-    const results = await mapLocalConcurrent(rows, concurrency, async (row) => {
-        const rowId = readLocalRowId(row);
-        if (!options.force && isNonEmptyLocalValue(row[column.key])) {
-            return {
-                status: "skipped",
-                rowId,
-                reason: "existing_value",
-                toolId: "custom_http",
-            };
-        }
-        try {
-            const execution = await executeLocalCustomHttpColumn(definition, row, secrets);
-            const update = await requestOxygen("/api/cli/tables/rows/update", {
-                method: "POST",
-                body: {
-                    table,
-                    row_id: rowId,
-                    values: { [column.key]: execution.output },
-                    metadata: {
-                        command: "columns run --local",
-                        column_key: column.key,
-                        column_kind: "tool",
-                        tool_mode: "custom_http",
-                        request: execution.request,
-                        response: execution.response,
-                        http_status: execution.response.status,
-                    },
-                },
-            });
-            return {
-                status: "completed",
-                rowId,
-                toolId: "custom_http",
-                request: execution.request,
-                response: execution.response,
-                output: execution.output,
-                run: isRecord(update.run) ? update.run : null,
-            };
-        }
-        catch (error) {
-            const serialized = serializeLocalColumnError(error, "custom_http_run_failed");
-            const update = await requestOxygen("/api/cli/tables/rows/update", {
-                method: "POST",
-                body: {
-                    table,
-                    row_id: rowId,
-                    values: { [column.key]: serialized },
-                    metadata: {
-                        command: "columns run --local",
-                        column_key: column.key,
-                        column_kind: "tool",
-                        tool_mode: "custom_http",
-                        error: serialized.error,
-                    },
-                },
-            });
-            return {
-                status: "failed",
-                rowId,
-                toolId: "custom_http",
-                output: serialized,
-                error: serialized.error,
-                run: isRecord(update.run) ? update.run : null,
-            };
-        }
-    });
-    const completedCount = results.filter((result) => result.status === "completed").length;
-    const failedCount = results.filter((result) => result.status === "failed").length;
-    const skippedCount = results.filter((result) => result.status === "skipped").length;
-    const first = results[0];
+    const results = await mapLocalConcurrent(rows, concurrency, (row) => runLocalCustomHttpRow({
+        table,
+        columnKey: column.key,
+        definition,
+        row,
+        secrets,
+        force: options.force,
+    }));
+    const { completedCount, failedCount, skippedCount } = countLocalCustomHttpResults(results);
     return {
-        status: failedCount > 0
-            ? "completed_with_errors"
-            : completedCount > 0
-                ? "completed"
-                : "skipped",
+        status: localCustomHttpRunStatus({ completedCount, failedCount, skippedCount }),
         table: described.table ?? queried.table ?? null,
         column,
         toolId: "custom_http",
@@ -103,13 +42,109 @@ export async function runLocalCustomHttpColumn(table, columnKeyOrId, options) {
         failedCount,
         skippedCount,
         results,
-        ...(first ? { rowId: first.rowId } : {}),
-        ...(first && "request" in first ? { request: first.request } : {}),
-        ...(first && "output" in first ? { output: first.output } : {}),
-        ...(first && "error" in first ? { error: first.error } : {}),
-        ...(first && "run" in first ? { run: first.run } : {}),
+        ...localFirstRowFields(results[0]),
+    };
+}
+async function runLocalCustomHttpRow(input) {
+    const rowId = readLocalRowId(input.row);
+    if (!input.force && isNonEmptyLocalValue(input.row[input.columnKey])) {
+        return {
+            status: "skipped",
+            rowId,
+            reason: "existing_value",
+            toolId: "custom_http",
+        };
+    }
+    try {
+        const execution = await executeLocalCustomHttpColumn(input.definition, input.row, input.secrets);
+        return await persistLocalCustomHttpSuccess({ ...input, rowId, execution });
+    }
+    catch (error) {
+        return await persistLocalCustomHttpFailure({ ...input, rowId, error });
+    }
+}
+async function persistLocalCustomHttpSuccess(input) {
+    const update = await requestOxygen("/api/cli/tables/rows/update", {
+        method: "POST",
+        body: {
+            table: input.table,
+            row_id: input.rowId,
+            values: { [input.columnKey]: input.execution.output },
+            metadata: {
+                command: "columns run --local",
+                column_key: input.columnKey,
+                column_kind: "tool",
+                tool_mode: "custom_http",
+                request: input.execution.request,
+                response: input.execution.response,
+                http_status: input.execution.response.status,
+            },
+        },
+    });
+    return {
+        status: "completed",
+        rowId: input.rowId,
+        toolId: "custom_http",
+        request: input.execution.request,
+        response: input.execution.response,
+        output: input.execution.output,
+        run: isRecord(update.run) ? update.run : null,
+    };
+}
+async function persistLocalCustomHttpFailure(input) {
+    const serialized = serializeLocalColumnError(input.error, "custom_http_run_failed");
+    const update = await requestOxygen("/api/cli/tables/rows/update", {
+        method: "POST",
+        body: {
+            table: input.table,
+            row_id: input.rowId,
+            values: { [input.columnKey]: serialized },
+            metadata: {
+                command: "columns run --local",
+                column_key: input.columnKey,
+                column_kind: "tool",
+                tool_mode: "custom_http",
+                error: serialized.error,
+            },
+        },
+    });
+    return {
+        status: "failed",
+        rowId: input.rowId,
+        toolId: "custom_http",
+        output: serialized,
+        error: serialized.error,
+        run: isRecord(update.run) ? update.run : null,
+    };
+}
+function countLocalCustomHttpResults(results) {
+    return {
+        completedCount: results.filter((result) => result.status === "completed").length,
+        failedCount: results.filter((result) => result.status === "failed").length,
+        skippedCount: results.filter((result) => result.status === "skipped").length,
     };
 }
+function localCustomHttpRunStatus(counts) {
+    if (counts.failedCount > 0)
+        return "completed_with_errors";
+    if (counts.completedCount > 0)
+        return "completed";
+    return "skipped";
+}
+function localFirstRowFields(first) {
+    if (!first)
+        return {};
+    const fields = { rowId: first.rowId };
+    if ("request" in first)
+        fields.request = first.request;
+    if ("output" in first)
+        fields.output = first.output;
+    if ("error" in first)
+        fields.error = first.error;
+    if ("run" in first)
+        fields.run = first.run;
+    return fields;
+}
 function findLocalColumn(columns, columnKeyOrId) {
     const column = columns.find((entry) => entry.id === columnKeyOrId || entry.key === columnKeyOrId);
     if (!column) {
@@ -284,46 +319,94 @@ async function mapLocalConcurrent(values, concurrency, action) {
     return results;
 }
 async function executeLocalCustomHttpColumn(definition, row, secrets) {
+    const prepared = prepareLocalCustomHttpRequest(definition, row, secrets);
+    const response = await fetchLocalCustomHttpResponse(prepared);
+    return await readLocalCustomHttpExecution(response, prepared, definition.outputPath ?? null);
+}
+function prepareLocalCustomHttpRequest(definition, row, secrets) {
     const secretValues = Object.values(secrets);
     const method = definition.request.method;
-    const resolvedUrl = resolveLocalTemplateString(definition.request.url, row, secrets, "request.url");
-    if (typeof resolvedUrl !== "string" || !resolvedUrl.trim()) {
-        throw new OxygenError("invalid_column_run", "Custom HTTP request url must resolve to a string.", {
-            details: { field: "request.url" },
-            exitCode: 1,
-        });
-    }
-    const url = validateLocalHttpUrl(resolvedUrl, secretValues);
+    const url = resolveLocalHttpUrl(definition.request.url, row, secrets, secretValues);
     const headers = resolveLocalHeaders(definition.request.headers ?? {}, row, secrets);
-    const bodyValue = Object.hasOwn(definition.request, "body")
+    const bodyValue = resolveLocalHttpBodyValue(definition, row, secrets);
+    assertLocalHttpBodyAllowed(method, bodyValue);
+    const body = bodyValue === undefined ? undefined : serializeLocalHttpBody(bodyValue, headers);
+    return { method, url, headers, bodyValue, body, secretValues };
+}
+function resolveLocalHttpUrl(template, row, secrets, secretValues) {
+    const resolvedUrl = resolveLocalTemplateString(template, row, secrets, "request.url");
+    if (typeof resolvedUrl === "string" && resolvedUrl.trim())
+        return validateLocalHttpUrl(resolvedUrl, secretValues);
+    throw new OxygenError("invalid_column_run", "Custom HTTP request url must resolve to a string.", {
+        details: { field: "request.url" },
+        exitCode: 1,
+    });
+}
+function resolveLocalHttpBodyValue(definition, row, secrets) {
+    return Object.hasOwn(definition.request, "body")
         ? resolveLocalTemplateValue(definition.request.body, row, secrets, "request.body")
         : undefined;
+}
+function assertLocalHttpBodyAllowed(method, bodyValue) {
     if (method === "GET" && bodyValue !== undefined) {
         throw new OxygenError("invalid_column_run", "GET custom HTTP requests cannot include a body.", {
             details: { method },
             exitCode: 1,
         });
     }
-    const body = bodyValue === undefined ? undefined : serializeLocalHttpBody(bodyValue, headers);
-    const response = await fetch(url, {
-        method,
-        headers,
-        ...(body !== undefined ? { body } : {}),
+}
+async function fetchLocalCustomHttpResponse(prepared) {
+    return await fetch(prepared.url, {
+        method: prepared.method,
+        headers: prepared.headers,
+        ...(prepared.body !== undefined ? { body: prepared.body } : {}),
+        redirect: "manual",
+        signal: AbortSignal.timeout(LOCAL_CUSTOM_HTTP_TIMEOUT_MS),
     }).catch((error) => {
         throw new OxygenError("custom_http_network_error", "Custom HTTP request failed before receiving a response.", {
             details: {
-                reason: redactLocalSecrets(error instanceof Error ? error.message : String(error), secretValues),
+                reason: redactLocalSecrets(error instanceof Error ? error.message : String(error), prepared.secretValues),
             },
             exitCode: 1,
         });
     });
-    const responseBody = await readLocalHttpResponseBody(response);
-    const redactedResponseBody = redactLocalSecrets(responseBody, secretValues);
-    const responseSummary = {
+}
+async function readLocalCustomHttpExecution(response, prepared, outputPath) {
+    assertLocalNoRedirect(response, prepared.secretValues);
+    const responseBody = await readLocalHttpResponseBody(response, LOCAL_CUSTOM_HTTP_MAX_RESPONSE_BYTES);
+    const redactedResponseBody = redactLocalSecrets(responseBody, prepared.secretValues);
+    const responseSummary = summarizeLocalHttpResponse(response, prepared.secretValues);
+    assertLocalOkResponse(response, redactedResponseBody);
+    return {
+        output: applyLocalOutputPath(redactedResponseBody, outputPath),
+        request: redactLocalSecrets({
+            method: prepared.method,
+            url: prepared.url,
+            ...(Object.keys(prepared.headers).length > 0 ? { headers: prepared.headers } : {}),
+            ...(prepared.bodyValue !== undefined ? { body: prepared.bodyValue } : {}),
+        }, prepared.secretValues),
+        response: responseSummary,
+    };
+}
+function assertLocalNoRedirect(response, secretValues) {
+    if (response.status >= 300 && response.status < 400) {
+        throw new OxygenError("custom_http_redirect_blocked", "Custom HTTP redirects are blocked for safety.", {
+            details: {
+                status: response.status,
+                location: redactLocalSecrets(response.headers.get("location") ?? null, secretValues),
+            },
+            exitCode: 1,
+        });
+    }
+}
+function summarizeLocalHttpResponse(response, secretValues) {
+    return {
         status: response.status,
         statusText: response.statusText,
         headers: redactLocalSecrets(localHeadersToObject(response.headers), secretValues),
     };
+}
+function assertLocalOkResponse(response, redactedResponseBody) {
     if (!response.ok) {
         throw new OxygenError("custom_http_request_failed", "Custom HTTP request returned a non-2xx response.", {
             details: {
@@ -334,22 +417,11 @@ async function executeLocalCustomHttpColumn(definition, row, secrets) {
             exitCode: 1,
         });
     }
-    return {
-        output: applyLocalOutputPath(redactedResponseBody, definition.outputPath ?? null),
-        request: redactLocalSecrets({
-            method,
-            url,
-            ...(Object.keys(headers).length > 0 ? { headers } : {}),
-            ...(bodyValue !== undefined ? { body: bodyValue } : {}),
-        }, secretValues),
-        response: responseSummary,
-    };
 }
 function validateLocalHttpUrl(rawUrl, secretValues) {
     try {
         const parsed = new URL(rawUrl);
-        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
-            throw new Error("Unsupported protocol.");
+        validateLocalPublicHttpsUrl(parsed);
         return parsed.toString();
     }
     catch (error) {
@@ -362,6 +434,113 @@ function validateLocalHttpUrl(rawUrl, secretValues) {
         });
     }
 }
+function validateLocalPublicHttpsUrl(parsed) {
+    if (parsed.protocol !== "https:")
+        throw new Error("Custom HTTP URLs must use https.");
+    if (parsed.username || parsed.password)
+        throw new Error("Custom HTTP URLs cannot contain username or password credentials.");
+    const host = normalizeLocalUrlHost(parsed.hostname);
+    if (isBlockedLocalCustomHttpHost(host))
+        throw new Error("Custom HTTP URL host is not allowed.");
+}
+function normalizeLocalUrlHost(hostname) {
+    const host = hostname.toLowerCase().replace(/\.+$/, "");
+    return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+function isBlockedLocalCustomHttpHost(host) {
+    return host === "localhost"
+        || host.endsWith(".localhost")
+        || host === "metadata.google.internal"
+        || isBlockedLocalIpv4Address(host)
+        || isBlockedLocalIpv6Address(host);
+}
+function isBlockedLocalIpv4Address(host) {
+    const address = isIP(host) === 4 ? host : readLeadingLocalIpv4Label(host);
+    if (!address)
+        return false;
+    const parts = address.split(".").map((part) => Number(part));
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+        return true;
+    const [a = 0, b = 0] = parts;
+    return a === 0
+        || a === 10
+        || a === 127
+        || (a === 169 && b === 254)
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168)
+        || (a === 100 && b >= 64 && b <= 127)
+        || (a === 192 && b === 0)
+        || (a === 198 && (b === 18 || b === 19))
+        || a >= 224;
+}
+function readLeadingLocalIpv4Label(host) {
+    const match = /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})(?:\.|$)/.exec(host);
+    return match?.[1] ?? null;
+}
+function isBlockedLocalIpv6Address(host) {
+    if (isIP(host) !== 6)
+        return false;
+    const groups = expandLocalIpv6Groups(host);
+    if (!groups)
+        return true;
+    const mappedIpv4 = localIpv4FromIpv6(groups);
+    if (mappedIpv4 && isBlockedLocalIpv4Address(mappedIpv4))
+        return true;
+    const [first = 0, second = 0] = groups;
+    const isUnspecified = groups.every((group) => group === 0);
+    const isLoopback = groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1;
+    return isUnspecified
+        || isLoopback
+        || (first & 0xfe00) === 0xfc00
+        || (first & 0xffc0) === 0xfe80
+        || (first & 0xff00) === 0xff00
+        || (first === 0x2001 && second === 0x0db8);
+}
+function expandLocalIpv6Groups(host) {
+    const address = host.toLowerCase();
+    const doubleColonParts = address.split("::");
+    if (doubleColonParts.length > 2)
+        return null;
+    const head = splitLocalIpv6Part(doubleColonParts[0] ?? "");
+    const tail = splitLocalIpv6Part(doubleColonParts[1] ?? "");
+    if (!head || !tail)
+        return null;
+    const fill = doubleColonParts.length === 2 ? 8 - head.length - tail.length : 0;
+    if (fill < 0)
+        return null;
+    const groups = doubleColonParts.length === 2
+        ? [...head, ...Array.from({ length: fill }, () => 0), ...tail]
+        : head;
+    return groups.length === 8 ? groups : null;
+}
+function splitLocalIpv6Part(part) {
+    if (!part)
+        return [];
+    const groups = part.split(":");
+    const values = [];
+    for (const group of groups) {
+        if (!/^[0-9a-f]{1,4}$/.test(group))
+            return null;
+        values.push(Number.parseInt(group, 16));
+    }
+    return values;
+}
+function localIpv4FromIpv6(groups) {
+    const mappedPrefix = groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff;
+    const compatiblePrefix = groups.slice(0, 6).every((group) => group === 0);
+    if (!mappedPrefix && !compatiblePrefix)
+        return null;
+    const high = groups[6] ?? 0;
+    const low = groups[7] ?? 0;
+    if (high === 0 && low === 0)
+        return null;
+    return [
+        high >> 8,
+        high & 0xff,
+        low >> 8,
+        low & 0xff,
+    ].join(".");
+}
 function resolveLocalHeaders(headers, row, secrets) {
     const resolved = {};
     for (const [key, value] of Object.entries(headers)) {
@@ -382,8 +561,17 @@ function hasLocalHeader(headers, name) {
     const normalized = name.toLowerCase();
     return Object.keys(headers).some((key) => key.toLowerCase() === normalized);
 }
-async function readLocalHttpResponseBody(response) {
-    const text = await response.text();
+async function readLocalHttpResponseBody(response, maxBytes) {
+    const contentLength = response.headers.get("content-length");
+    const declaredLength = contentLength === null ? null : Number(contentLength);
+    if (declaredLength !== null && Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+        throw new OxygenError("custom_http_response_too_large", "Custom HTTP response exceeds the configured size cap.", {
+            details: { max_response_bytes: maxBytes, content_length: declaredLength },
+            exitCode: 1,
+        });
+    }
+    const buffer = await readLocalHttpResponseBuffer(response, maxBytes);
+    const text = buffer.toString("utf8");
     if (!text)
         return null;
     const contentType = response.headers.get("content-type") ?? "";
@@ -403,6 +591,41 @@ async function readLocalHttpResponseBody(response) {
         return text;
     }
 }
+async function readLocalHttpResponseBuffer(response, maxBytes) {
+    if (!response.body) {
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > maxBytes) {
+            throw new OxygenError("custom_http_response_too_large", "Custom HTTP response exceeds the configured size cap.", {
+                details: { max_response_bytes: maxBytes, actual_bytes: buffer.byteLength },
+                exitCode: 1,
+            });
+        }
+        return Buffer.from(buffer);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let actualBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            actualBytes += value.byteLength;
+            if (actualBytes > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw new OxygenError("custom_http_response_too_large", "Custom HTTP response exceeds the configured size cap.", {
+                    details: { max_response_bytes: maxBytes, actual_bytes: actualBytes },
+                    exitCode: 1,
+                });
+            }
+            chunks.push(Buffer.from(value));
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, actualBytes);
+}
 function localHeadersToObject(headers) {
     const result = {};
     headers.forEach((value, key) => {
@@ -434,10 +657,17 @@ function resolveLocalTemplateString(value, row, secrets, inputName) {
     });
 }
 function resolveLocalTemplatePath(rawPath, row, secrets, inputName) {
-    const segments = rawPath
+    const segments = splitLocalTemplatePath(rawPath);
+    const root = resolveLocalTemplateRoot(segments, row, secrets, inputName, rawPath);
+    return resolveLocalTemplateSegments(root.current, root.segments);
+}
+function splitLocalTemplatePath(rawPath) {
+    return rawPath
         .split(".")
         .map((segment) => segment.trim())
         .filter(Boolean);
+}
+function resolveLocalTemplateRoot(segments, row, secrets, inputName, rawPath) {
     const root = segments.shift();
     if (!root) {
         throw new OxygenError("invalid_column_run", "Template reference is empty.", {
@@ -445,40 +675,47 @@ function resolveLocalTemplatePath(rawPath, row, secrets, inputName) {
             exitCode: 1,
         });
     }
-    let current;
     if (root === "secrets") {
-        const secretName = segments.shift();
-        if (!secretName || !Object.hasOwn(secrets, secretName)) {
-            throw new OxygenError("invalid_column_run", "Template references an unknown custom HTTP secret.", {
-                details: { input: inputName, secret: secretName ?? null, template: rawPath },
-                exitCode: 1,
-            });
-        }
-        current = secrets[secretName];
+        return resolveLocalTemplateSecretRoot(segments, secrets, inputName, rawPath);
     }
-    else {
-        if (!Object.hasOwn(row, root)) {
-            throw new OxygenError("invalid_column_run", "Template references an unknown row column.", {
-                details: { input: inputName, column_key: root, template: rawPath },
-                exitCode: 1,
-            });
-        }
-        current = row[root];
+    return resolveLocalTemplateRowRoot(root, segments, row, inputName, rawPath);
+}
+function resolveLocalTemplateSecretRoot(segments, secrets, inputName, rawPath) {
+    const secretName = segments.shift();
+    if (!secretName || !Object.hasOwn(secrets, secretName)) {
+        throw new OxygenError("invalid_column_run", "Template references an unknown custom HTTP secret.", {
+            details: { input: inputName, secret: secretName ?? null, template: rawPath },
+            exitCode: 1,
+        });
     }
+    return { current: secrets[secretName], segments };
+}
+function resolveLocalTemplateRowRoot(root, segments, row, inputName, rawPath) {
+    if (!Object.hasOwn(row, root)) {
+        throw new OxygenError("invalid_column_run", "Template references an unknown row column.", {
+            details: { input: inputName, column_key: root, template: rawPath },
+            exitCode: 1,
+        });
+    }
+    return { current: row[root], segments };
+}
+function resolveLocalTemplateSegments(current, segments) {
+    let value = current;
     for (const segment of segments) {
-        if (current === null || current === undefined)
+        value = resolveLocalTemplateSegment(value, segment);
+        if (value === null)
             return null;
-        if (Array.isArray(current) && /^\d+$/.test(segment)) {
-            current = current[Number(segment)] ?? null;
-            continue;
-        }
-        if (isRecord(current) && Object.hasOwn(current, segment)) {
-            current = current[segment];
-            continue;
-        }
-        return null;
     }
-    return current ?? null;
+    return value ?? null;
+}
+function resolveLocalTemplateSegment(current, segment) {
+    if (current === null || current === undefined)
+        return null;
+    if (Array.isArray(current) && /^\d+$/.test(segment))
+        return current[Number(segment)] ?? null;
+    if (isRecord(current) && Object.hasOwn(current, segment))
+        return current[segment];
+    return null;
 }
 function applyLocalOutputPath(value, outputPath) {
     const path = typeof outputPath === "string" ? outputPath.trim() : "";

package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Signed token for the RFC 8058 one-click List-Unsubscribe link on native cold
+ * email. The worker MINTS the token at send time and bakes the URL into the
+ * List-Unsubscribe header; the public web webhook VERIFIES it. The token is the
+ * ONLY credential the anonymous unsubscribe endpoint trusts, so it must bind the
+ * recipient address — never let the caller pass an arbitrary email. The signing
+ * key (EMAIL_UNSUBSCRIBE_SECRET) lives in Doppler oxygen-shared so both the
+ * worker (mint) and web (verify) read the same value.
+ *
+ * Layering: this lives in @oxygen/shared because neither the worker nor the
+ * integrations send path can import apps/web, and the web route cannot import the
+ * worker. Pure + stateless: crypto only, no env policy (the route decides what a
+ * null verify means — a 401).
+ */
+export type UnsubscribeTokenPayload = {
+    /** Schema version; only v1 is accepted. */
+    v: 1;
+    /** Organization id (also the webhook path segment; the route re-checks it). */
+    org: string;
+    /** The recipient address to suppress (normalized trim+lowercase, = the suppression key). */
+    email: string;
+    /** Sequence id, for provenance on the suppression row. */
+    seq?: string;
+    /** Enrollment id, so a one-click stop can halt the exact journey. */
+    enr?: string;
+    /** Sending mailbox id, for provenance. */
+    mbx?: string;
+    /** Issued-at (epoch ms), recorded as provenance. */
+    iat: number;
+};
+type EnvLike = Record<string, string | undefined>;
+/**
+ * Sign a payload into `<base64url(json)>.<base64url(hmac-sha256)>`. The HMAC is
+ * computed over the encoded body, so any tamper to the payload invalidates the
+ * signature. Normalizes the email to the stored suppression form so the webhook
+ * write and the pre-send gate key on the identical string.
+ */
+export declare function signUnsubscribeToken(payload: UnsubscribeTokenPayload, secret: string): string;
+/**
+ * Verify a token's signature (constant-time) and shape. Returns the payload only
+ * when the signature matches AND it is a well-formed v1 payload with a non-empty
+ * org + a plausible email; returns null on ANY problem (bad shape, wrong/blank
+ * secret, tampered body, replayed garbage). Pure: the route maps null -> 401.
+ */
+export declare function verifyUnsubscribeToken(token: string, secret: string): UnsubscribeTokenPayload | null;
+/**
+ * The HMAC signing secret for unsubscribe tokens, or null when unset. The send
+ * path treats null as "omit the header" (a send with no one-click link still
+ * delivers); the webhook route treats null as fail-closed (reject everything).
+ */
+export declare function unsubscribeSigningSecret(env?: EnvLike): string | null;
+/**
+ * The public app base URL the unsubscribe link points at, trailing slash
+ * stripped. Prefers NEXT_PUBLIC_APP_URL, then OXYGEN_APP_URL, then the prod host.
+ */
+export declare function oxygenAppBaseUrl(env?: EnvLike): string;
+/**
+ * The canonical one-click unsubscribe URL: org id in the path (the route
+ * re-checks it against the token), token in the `token` query param.
+ */
+export declare function buildUnsubscribeUrl(orgId: string, token: string, baseUrl: string): string;
+export {};