@opencoredev/social-sdk 0.2.1 → 0.4.0

package/dist/server/webhooks.js

@@ -1,13 +1,9 @@
-/* oxlint-disable anti-slop/no-runtime-typeof, anti-slop/no-unknown-parameters, anti-slop/no-unsafe-dictionary-type, anti-slop/require-safety-comment-for-type-assertion -- webhook bodies are unknown until validated by the decoder. */
 import { parseJson } from "../transport/json.js";
 import { SocialError } from "../core/errors.js";
-import { array, object, optionalString, string } from "../transport/validation.js";
-function denied() {
-    throw new SocialError({
-        code: "unauthorized",
-        operation: "webhooks.verify",
-        message: "Webhook authentication failed. Check the configured endpoint secret and preserve the raw request bytes.",
-    });
+import { definedFields } from "../core/fields.js";
+import { array, isFiniteNumber, isJsonArray, isJsonObject, isString, object, optionalString, string, } from "../transport/validation.js";
+function denied(message = "Webhook authentication failed. Check the configured endpoint secret and preserve the raw request bytes.") {
+    throw new SocialError({ code: "unauthorized", operation: "webhooks.verify", message });
 }
 function checkedBytes(body, maxBytes) {
     if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || body.byteLength > maxBytes)
@@ -46,24 +42,35 @@ export async function verifyPostForMeWebhook(input) {
     };
 }
 const sensitive = /^(access.?token|refresh.?token|authorization|cookie|secret|signature|code|password|signed.?url|upload.?url)$/i;
-function clean(value, depth = 0) {
+/** Objects and arrays: the values a truthy `typeof value === "object"` check admits. */
+function isStructured(value) {
+    return isJsonObject(value) || isJsonArray(value);
+}
+function checkDepth(depth) {
     if (depth > 32)
         throw new SocialError({
             code: "invalid_input",
             operation: "webhooks.decode",
             message: "Webhook payload nesting exceeds the limit.",
         });
-    if (value === null || typeof value === "boolean" || typeof value === "number")
-        return value;
-    if (typeof value === "string") {
+}
+function clean(value, depth) {
+    checkDepth(depth);
+    if (isString(value)) {
         if (/https:\/\//i.test(value) && /[?&](x-amz-|signature|token|sig|key)=?/i.test(value))
             return "[redacted URL]";
         return value;
     }
-    if (Array.isArray(value))
+    if (isJsonArray(value))
         return value.map((item) => clean(item, depth + 1));
+    if (isJsonObject(value))
+        return cleanObject(value, depth);
+    return value;
+}
+function cleanObject(value, depth = 0) {
+    checkDepth(depth);
     const result = {};
-    for (const [key, entry] of Object.entries(object(value)))
+    for (const [key, entry] of Object.entries(value))
         result[key] = sensitive.test(key) ? "[redacted]" : clean(entry, depth + 1);
     return result;
 }
@@ -103,16 +110,15 @@ export async function decodeWebhook(input) {
     else if (originalType === "comment.received")
         type = "comment.received";
     const dataValue = input.provider === "zernio" ? payload : object(payload["data"]);
-    const cleaned = clean(dataValue);
-    if (typeof cleaned !== "object" || cleaned === null || Array.isArray(cleaned))
-        throw new Error("Expected normalized object");
+    const cleaned = cleanObject(dataValue);
     // IDs only locate application mappings; they never grant tenant ownership.
     const accountIds = [];
     const direct = optionalString(dataValue["accountId"]) ?? optionalString(dataValue["social_account_id"]);
     if (direct)
         accountIds.push(direct);
-    if (dataValue["account"] && typeof dataValue["account"] === "object") {
-        const account = object(dataValue["account"]);
+    const accountValue = dataValue["account"];
+    if (isStructured(accountValue)) {
+        const account = object(accountValue);
         const accountId = optionalString(account["accountId"]) ??
             optionalString(account["_id"]) ??
             optionalString(account["id"]);
@@ -121,8 +127,9 @@ export async function decodeWebhook(input) {
     }
     if (input.provider === "post-for-me" && originalType.startsWith("social.account."))
         accountIds.push(string(dataValue["id"]));
-    if (dataValue["post"] && typeof dataValue["post"] === "object") {
-        const post = object(dataValue["post"]);
+    const postValue = dataValue["post"];
+    if (isStructured(postValue)) {
+        const post = object(postValue);
         if (post["platforms"])
             for (const value of array(post["platforms"])) {
                 const entry = object(value);
@@ -133,14 +140,12 @@ export async function decodeWebhook(input) {
     }
     if (input.provider === "post-for-me" && Array.isArray(dataValue["social_accounts"])) {
         for (const item of dataValue["social_accounts"]) {
-            const id = typeof item === "string" ? item : optionalString(object(item)["id"]);
+            const id = isString(item) ? item : optionalString(object(item)["id"]);
             if (id)
                 accountIds.push(id);
         }
     }
-    const post = dataValue["post"] && typeof dataValue["post"] === "object"
-        ? object(dataValue["post"])
-        : undefined;
+    const post = isStructured(postValue) ? object(postValue) : undefined;
     const backendRecordId = input.provider === "zernio"
         ? (optionalString(post?.["id"]) ?? optionalString(post?.["_id"]))
         : originalType === "social.post.result.created"
@@ -202,3 +207,612 @@ export async function acceptWebhook(input) {
     });
     return { state, quarantined };
 }
+const encoder = new TextEncoder();
+const defaultMaxBytes = 1024 * 1024;
+function challengeRefused(code) {
+    throw new SocialError({
+        code,
+        operation: "webhooks.challenge",
+        message: "Webhook handshake refused. Check the configured token or topic and the request query.",
+    });
+}
+async function hmacKey(secret, hash, usages) {
+    return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash }, false, usages);
+}
+function hexBytes(value, length) {
+    if (value.length !== length * 2 || !/^[0-9a-f]+$/i.test(value))
+        return undefined;
+    const bytes = new Uint8Array(length);
+    for (let index = 0; index < length; index++)
+        bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+    return bytes;
+}
+function base64Bytes(value, length) {
+    if (value.length !== Math.ceil(length / 3) * 4 || !/^[A-Za-z0-9+/]+={0,2}$/.test(value))
+        return undefined;
+    let binary;
+    try {
+        binary = atob(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (binary.length !== length)
+        return undefined;
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function base64(bytes) {
+    let binary = "";
+    for (const byte of new Uint8Array(bytes))
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+async function hmacMatches(secret, hash, signature, data) {
+    // WebCrypto compares the keyed digest itself, avoiding a JS early-exit comparison.
+    return crypto.subtle.verify("HMAC", await hmacKey(secret, hash, ["verify"]), signature, data);
+}
+async function sameSecret(expected, supplied) {
+    // Compare fixed-size keyed digests so the token length and prefix do not leak through timing.
+    const key = await hmacKey(expected, "SHA-256", ["sign", "verify"]);
+    const digest = await crypto.subtle.sign("HMAC", key, encoder.encode(expected));
+    return crypto.subtle.verify("HMAC", key, digest, encoder.encode(supplied));
+}
+function bodyVerified(method) {
+    return { valid: true, method, bodyAuthenticated: true, signedTimestamp: false };
+}
+/**
+ * Verify a Meta webhook POST for Instagram or Threads. Meta signs the raw body with
+ * HMAC-SHA256 using the app secret and sends `X-Hub-Signature-256: sha256=<hex>`.
+ */
+export async function verifyMetaWebhook(input) {
+    const body = checkedBytes(input.body, input.maxBytes ?? defaultMaxBytes);
+    if (!input.secret)
+        denied();
+    const match = /^sha256=([0-9a-f]{64})$/i.exec(input.headers.get("X-Hub-Signature-256") ?? "");
+    const signature = match?.[1] === undefined ? undefined : hexBytes(match[1], 32);
+    if (!signature || !(await hmacMatches(input.secret, "SHA-256", signature, body)))
+        denied();
+    return bodyVerified("hmac-sha256");
+}
+/**
+ * Answer Meta's GET verification request. The verify token is compared in constant
+ * time and only a bounded, token-safe `hub.challenge` is echoed.
+ */
+export async function answerMetaWebhookChallenge(input) {
+    const token = input.query.get("hub.verify_token");
+    const challenge = input.query.get("hub.challenge");
+    if (!input.verifyToken ||
+        input.query.get("hub.mode") !== "subscribe" ||
+        !token ||
+        token.length > 4096 ||
+        !challenge ||
+        !/^[A-Za-z0-9_-]{1,256}$/.test(challenge) ||
+        !(await sameSecret(input.verifyToken, token)))
+        challengeRefused("unauthorized");
+    return {
+        status: 200,
+        headers: { "Content-Type": "text/plain; charset=utf-8", "X-Content-Type-Options": "nosniff" },
+        body: challenge,
+    };
+}
+/**
+ * Verify an X webhook POST. X signs the raw body with HMAC-SHA256 and sends
+ * `sha256=<base64>` in `X-Twitter-Webhooks-Signature-OAuth2` (OAuth 2.0 client secret)
+ * or the legacy `X-Twitter-Webhooks-Signature` (OAuth 1.0 consumer secret). When the
+ * OAuth 2.0 header is present it alone decides; the legacy header is checked only when
+ * the OAuth 2.0 header is absent. Pass the secret that matches the header X sends.
+ */
+export async function verifyXWebhook(input) {
+    const body = checkedBytes(input.body, input.maxBytes ?? defaultMaxBytes);
+    if (!input.secret)
+        denied();
+    // X says to verify the OAuth 2.0 header when present. The legacy header is only a
+    // fallback when the OAuth 2.0 header is absent, so a bad OAuth 2.0 signature can
+    // never be rescued by a matching legacy one.
+    const header = input.headers.get("X-Twitter-Webhooks-Signature-OAuth2") ??
+        input.headers.get("X-Twitter-Webhooks-Signature");
+    const match = /^sha256=([A-Za-z0-9+/]{43}=)$/.exec(header ?? "");
+    const signature = match?.[1] === undefined ? undefined : base64Bytes(match[1], 32);
+    if (!signature || !(await hmacMatches(input.secret, "SHA-256", signature, body)))
+        denied();
+    return bodyVerified("hmac-sha256");
+}
+/**
+ * Answer X's CRC GET request with `{"response_token":"sha256=<base64>"}`, an
+ * HMAC-SHA256 of `crc_token` keyed with the same secret used for signatures.
+ */
+export async function answerXWebhookChallenge(input) {
+    const crcToken = input.query.get("crc_token");
+    if (!input.secret || !crcToken || encoder.encode(crcToken).byteLength > 1024)
+        challengeRefused("unauthorized");
+    const digest = await crypto.subtle.sign("HMAC", await hmacKey(input.secret, "SHA-256", ["sign"]), encoder.encode(crcToken));
+    const responseToken = `sha256=${base64(digest)}`;
+    return {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ response_token: responseToken }),
+        responseToken,
+    };
+}
+function webSubAlgorithm(name) {
+    switch (name) {
+        case "sha1":
+            return { hash: "SHA-1", bytes: 20, method: "hmac-sha1" };
+        case "sha256":
+            return { hash: "SHA-256", bytes: 32, method: "hmac-sha256" };
+        case "sha384":
+            return { hash: "SHA-384", bytes: 48, method: "hmac-sha384" };
+        case "sha512":
+            return { hash: "SHA-512", bytes: 64, method: "hmac-sha512" };
+        default:
+            return undefined;
+    }
+}
+/**
+ * Verify a YouTube push notification delivered through the PubSubHubbub hub. The
+ * hub only signs deliveries when the subscription was created with `hub.secret`; it
+ * sends `X-Hub-Signature: <method>=<hex>`, and the reported method is returned.
+ */
+export async function verifyYouTubeWebhook(input) {
+    const body = checkedBytes(input.body, input.maxBytes ?? defaultMaxBytes);
+    if (!input.secret)
+        denied();
+    const match = /^(sha1|sha256|sha384|sha512)=([0-9a-f]+)$/i.exec(input.headers.get("X-Hub-Signature") ?? "");
+    const algorithm = webSubAlgorithm(match?.[1]?.toLowerCase());
+    const signature = algorithm === undefined || match?.[2] === undefined
+        ? undefined
+        : hexBytes(match[2], algorithm.bytes);
+    if (!algorithm ||
+        !signature ||
+        !(await hmacMatches(input.secret, algorithm.hash, signature, body)))
+        denied();
+    return bodyVerified(algorithm.method);
+}
+/**
+ * Answer the hub's GET verification of intent. The topic must be one the
+ * application is currently subscribing to or unsubscribing from; otherwise this
+ * throws `not_found`, which WebSub expects as an HTTP 404.
+ */
+export function answerYouTubeWebhookChallenge(input) {
+    const mode = input.query.get("hub.mode");
+    const topic = input.query.get("hub.topic");
+    const challenge = input.query.get("hub.challenge");
+    const lease = input.query.get("hub.lease_seconds");
+    if ((mode !== "subscribe" && mode !== "unsubscribe") ||
+        !topic ||
+        !input.topics.includes(topic) ||
+        !challenge ||
+        !/^[+\-./0-9=A-Z_a-z]{1,512}$/.test(challenge) ||
+        (lease !== null && !/^\d{1,10}$/.test(lease)))
+        challengeRefused("not_found");
+    const response = {
+        status: 200,
+        headers: { "Content-Type": "application/octet-stream", "X-Content-Type-Options": "nosniff" },
+        body: challenge,
+        mode,
+        topic,
+    };
+    return mode === "subscribe" && lease !== null
+        ? { ...response, leaseSeconds: Number(lease) }
+        : response;
+}
+/**
+ * Verify a TikTok webhook POST. `TikTok-Signature: t=<unix seconds>,s=<hex>` carries an
+ * HMAC-SHA256 of `<t>.<raw body>` keyed with the app's client secret. TikTok leaves
+ * the replay window to the receiver; this defaults to 300 seconds.
+ */
+export async function verifyTikTokWebhook(input) {
+    const body = checkedBytes(input.body, input.maxBytes ?? defaultMaxBytes);
+    const tolerance = input.toleranceSeconds ?? 300;
+    if (!Number.isSafeInteger(tolerance) || tolerance <= 0)
+        throw new SocialError({
+            code: "invalid_config",
+            operation: "webhooks.verify",
+            message: "TikTok webhook tolerance must be a positive whole number of seconds.",
+        });
+    if (!input.secret)
+        denied();
+    let timestamp;
+    let signatureHex;
+    for (const part of (input.headers.get("TikTok-Signature") ?? "").split(",")) {
+        const separator = part.indexOf("=");
+        if (separator < 0)
+            denied();
+        const key = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (key === "t") {
+            if (timestamp !== undefined)
+                denied();
+            timestamp = value;
+        }
+        else if (key === "s") {
+            if (signatureHex !== undefined)
+                denied();
+            signatureHex = value;
+        }
+    }
+    const signature = signatureHex === undefined ? undefined : hexBytes(signatureHex, 32);
+    if (!timestamp || !/^\d{1,12}$/.test(timestamp) || !signature)
+        denied();
+    const prefix = encoder.encode(`${timestamp}.`);
+    const signed = new Uint8Array(prefix.byteLength + body.byteLength);
+    signed.set(prefix);
+    signed.set(body, prefix.byteLength);
+    if (!(await hmacMatches(input.secret, "SHA-256", signature, signed)))
+        denied();
+    const seconds = Number(timestamp);
+    const now = Math.floor((input.now?.() ?? new Date()).getTime() / 1000);
+    if (Math.abs(now - seconds) > tolerance)
+        denied("Webhook signature is valid but its timestamp is outside the accepted window.");
+    return {
+        valid: true,
+        method: "hmac-sha256",
+        bodyAuthenticated: true,
+        signedTimestamp: true,
+        signedAt: new Date(seconds * 1000).toISOString(),
+    };
+}
+/**
+ * Verify a LinkedIn webhook POST. `X-LI-Signature` carries only the lowercase hex
+ * HMAC-SHA256 of the literal `hmacsha256=` followed by the raw body, keyed with the
+ * app's client secret. LinkedIn sends no signed timestamp.
+ */
+export async function verifyLinkedInWebhook(input) {
+    const body = checkedBytes(input.body, input.maxBytes ?? defaultMaxBytes);
+    if (!input.secret)
+        denied();
+    const signature = hexBytes((input.headers.get("X-LI-Signature") ?? "").trim(), 32);
+    if (!signature)
+        denied();
+    const prefix = encoder.encode("hmacsha256=");
+    const signed = new Uint8Array(prefix.byteLength + body.byteLength);
+    signed.set(prefix);
+    signed.set(body, prefix.byteLength);
+    if (!(await hmacMatches(input.secret, "SHA-256", signature, signed)))
+        denied();
+    return bodyVerified("hmac-sha256");
+}
+/**
+ * Answer LinkedIn's GET validation, which LinkedIn repeats every 2 hours. The
+ * response is `{ challengeCode, challengeResponse }`, where `challengeResponse` is the
+ * lowercase hex HMAC-SHA256 of `challengeCode` keyed with the client secret. For
+ * parent-child applications LinkedIn adds `applicationId`; pass `secretForApplication`
+ * to pick that application's client secret. An unknown application is refused.
+ */
+export async function answerLinkedInWebhookChallenge(input) {
+    const challengeCode = input.query.get("challengeCode");
+    const applicationId = input.query.get("applicationId");
+    if (!challengeCode || !/^[A-Za-z0-9-]{1,128}$/.test(challengeCode))
+        challengeRefused("unauthorized");
+    if (applicationId !== null && !/^[A-Za-z0-9_-]{1,128}$/.test(applicationId))
+        challengeRefused("unauthorized");
+    const secret = applicationId !== null && input.secretForApplication
+        ? input.secretForApplication(applicationId)
+        : input.secret;
+    if (!secret)
+        challengeRefused("unauthorized");
+    const digest = await crypto.subtle.sign("HMAC", await hmacKey(secret, "SHA-256", ["sign"]), encoder.encode(challengeCode));
+    const challengeResponse = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const response = {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ challengeCode, challengeResponse }),
+        challengeCode,
+        challengeResponse,
+    };
+    return applicationId === null ? response : { ...response, applicationId };
+}
+function malformed(platform) {
+    throw new SocialError({
+        code: "invalid_input",
+        operation: "webhooks.decode",
+        message: `Webhook body does not match the documented ${platform} notification shape.`,
+    });
+}
+function instagramFieldType(field) {
+    return field === "comments" || field === "live_comments" ? "comment.received" : "unknown";
+}
+function decodeInstagram(payload) {
+    const entries = array(payload["entry"]);
+    // A delivery without a documented container is malformed. A well-formed entry with
+    // a field the SDK does not map still decodes, as an `unknown` event.
+    if (payload["object"] !== "instagram" || entries.length === 0)
+        malformed("instagram");
+    const items = [];
+    const accountIds = [];
+    for (const value of entries) {
+        const entry = object(value);
+        const id = optionalString(entry["id"]);
+        if (id)
+            accountIds.push(id);
+        if (entry["changes"] !== undefined)
+            for (const change of array(entry["changes"])) {
+                const field = string(object(change)["field"]);
+                items.push({ originalType: field, type: instagramFieldType(field) });
+            }
+        if (entry["changed_fields"] !== undefined)
+            for (const value of array(entry["changed_fields"])) {
+                const field = string(value);
+                items.push({ originalType: field, type: instagramFieldType(field) });
+            }
+        if (entry["messaging"] !== undefined)
+            for (const item of array(entry["messaging"])) {
+                const messaging = object(item);
+                const message = messaging["message"];
+                if (message !== undefined) {
+                    const echo = object(message)["is_echo"] === true;
+                    items.push({
+                        originalType: echo ? "message_echoes" : "messages",
+                        type: echo ? "unknown" : "message.received",
+                    });
+                }
+                else if (messaging["reaction"] !== undefined)
+                    items.push({ originalType: "message_reactions", type: "unknown" });
+                else if (messaging["read"] !== undefined)
+                    items.push({ originalType: "messaging_seen", type: "unknown" });
+                else if (messaging["postback"] !== undefined)
+                    items.push({ originalType: "messaging_postbacks", type: "unknown" });
+                else
+                    items.push({ originalType: "messaging", type: "unknown" });
+            }
+    }
+    return { items, accountIds, data: payload };
+}
+function nestedString(value, key) {
+    return value === undefined ? undefined : optionalString(object(value)[key]);
+}
+function decodeThreads(payload) {
+    const values = object(payload["values"]);
+    const field = string(values["field"]);
+    const value = object(values["value"]);
+    // Threads identifies the owner differently per field. An unknown owner stays empty
+    // so acceptWebhook quarantines the event instead of guessing a tenant.
+    const owner = field === "replies"
+        ? nestedString(value["root_post"], "owner_id")
+        : field === "delete"
+            ? nestedString(value["owner"], "owner_id")
+            : field === "mentions"
+                ? optionalString(payload["target_id"])
+                : undefined;
+    const type = field === "replies" ? "comment.received" : field === "delete" ? "post.removed" : "unknown";
+    return {
+        items: [{ originalType: field, type }],
+        accountIds: owner ? [owner] : [],
+        data: payload,
+    };
+}
+function xEventType(key) {
+    if (key === "direct_message_events")
+        return "message.received";
+    if (key === "tweet_delete_events")
+        return "post.removed";
+    return "unknown";
+}
+function decodeX(payload) {
+    const items = [];
+    const accountIds = [];
+    const forUser = optionalString(payload["for_user_id"]);
+    if (forUser)
+        accountIds.push(forUser);
+    for (const [key, value] of Object.entries(payload))
+        if (key.endsWith("_events") && isJsonArray(value))
+            items.push({ originalType: key, type: xEventType(key) });
+    // X Activity API wraps each event in `data` with an `event_type`. It is a documented
+    // container, but its event types are not mapped, so it decodes as `unknown`.
+    const activity = payload["data"];
+    const activityType = isJsonObject(activity) ? optionalString(activity["event_type"]) : undefined;
+    if (activityType)
+        items.push({ originalType: activityType, type: "unknown" });
+    if (payload["user_event"] !== undefined) {
+        const userEvent = object(payload["user_event"]);
+        if (userEvent["revoke"] === undefined)
+            items.push({ originalType: "user_event", type: "unknown" });
+        else {
+            const userId = nestedString(object(userEvent["revoke"])["source"], "user_id");
+            if (userId)
+                accountIds.push(userId);
+            items.push({ originalType: "user_event.revoke", type: "account.updated" });
+        }
+    }
+    // `{}` or a body with only `for_user_id` carries no documented event container.
+    if (items.length === 0)
+        malformed("x");
+    return { items, accountIds, data: payload };
+}
+function xmlEntity(whole, entity) {
+    const name = entity.toLowerCase();
+    if (name === "amp")
+        return "&";
+    if (name === "lt")
+        return "<";
+    if (name === "gt")
+        return ">";
+    if (name === "quot")
+        return '"';
+    if (name === "apos")
+        return "'";
+    const code = name.startsWith("#x")
+        ? Number.parseInt(name.slice(2), 16)
+        : Number.parseInt(name.slice(1), 10);
+    return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+}
+function xmlText(value) {
+    const cdata = /^<!\[CDATA\[([\s\S]*)\]\]>$/.exec(value.trim());
+    if (cdata?.[1] !== undefined)
+        return cdata[1];
+    return value.trim().replace(/&(#x[0-9a-f]{1,6}|#\d{1,7}|amp|lt|gt|quot|apos);/gi, xmlEntity);
+}
+function xmlElement(block, name) {
+    const match = new RegExp(`<${name}(?:\\s[^>]*)?>([\\s\\S]*?)</${name}>`).exec(block);
+    return match?.[1] === undefined ? undefined : xmlText(match[1]);
+}
+function xmlAttribute(attributes, name) {
+    const match = new RegExp(`\\s${name}\\s*=\\s*"([^"]*)"`).exec(` ${attributes}`);
+    return match?.[1] === undefined ? undefined : xmlText(match[1]);
+}
+function decodeYouTube(text) {
+    // The hub delivers a small Atom document. Declarations are never needed, so they
+    // are rejected rather than expanded.
+    if (/<!DOCTYPE|<!ENTITY/i.test(text) || !/<feed[\s>]/.test(text))
+        malformed("youtube");
+    const items = [];
+    const accountIds = [];
+    const videos = [];
+    const deleted = [];
+    for (const match of text.matchAll(/<entry[\s>][\s\S]*?<\/entry>/g)) {
+        const block = match[0];
+        const videoId = xmlElement(block, "yt:videoId");
+        const channelId = xmlElement(block, "yt:channelId");
+        if (!videoId || !channelId)
+            malformed("youtube");
+        const title = xmlElement(block, "title");
+        const published = xmlElement(block, "published");
+        const updated = xmlElement(block, "updated");
+        // Absent Atom fields stay absent rather than becoming undefined.
+        const video = {
+            videoId,
+            channelId,
+            ...definedFields({ title, published, updated }),
+        };
+        accountIds.push(channelId);
+        videos.push(video);
+        items.push({ originalType: "yt:video", type: "unknown" });
+    }
+    // Atom tombstones (RFC 6721). YouTube's guide does not list deletion as a trigger,
+    // so this only decodes a tombstone if the hub sends one.
+    for (const match of text.matchAll(/<at:deleted-entry(\s[^>]*?)?(?:\/>|>([\s\S]*?)<\/at:deleted-entry>)/g)) {
+        const attributes = match[1] ?? "";
+        const ref = xmlAttribute(attributes, "ref");
+        const videoId = ref?.startsWith("yt:video:") ? ref.slice("yt:video:".length) : undefined;
+        if (!videoId)
+            malformed("youtube");
+        const when = xmlAttribute(attributes, "when");
+        const uri = xmlElement(match[2] ?? "", "uri");
+        const channelId = uri === undefined ? undefined : /\/channel\/([\w-]+)$/.exec(uri)?.[1];
+        if (channelId)
+            accountIds.push(channelId);
+        deleted.push({
+            videoId,
+            ...definedFields({ deletedAt: when || undefined, channelId: channelId || undefined }),
+        });
+        items.push({ originalType: "at:deleted-entry", type: "post.removed" });
+    }
+    if (items.length === 0)
+        malformed("youtube");
+    return { items, accountIds, data: { videos, deleted } };
+}
+function decodeLinkedIn(payload) {
+    const kind = string(payload["type"]);
+    const items = [];
+    const accountIds = [];
+    let lastModifiedAt;
+    if (kind === "ORGANIZATION_SOCIAL_ACTION_NOTIFICATIONS" && payload["notifications"] !== undefined)
+        for (const value of array(payload["notifications"])) {
+            const notification = object(value);
+            const action = string(notification["action"]);
+            const organization = optionalString(notification["organizationalEntity"]);
+            const modified = notification["lastModifiedAt"];
+            if (organization)
+                accountIds.push(organization);
+            if (isFiniteNumber(modified) && Number.isSafeInteger(modified) && modified > 0)
+                lastModifiedAt = Math.max(lastModifiedAt ?? 0, modified);
+            // Only a member comment is clearly an inbound comment. ADMIN_COMMENT is the
+            // page's own comment, and edits, deletions, likes, shares, and mentions have no
+            // normalized type, so they stay `unknown` with the action as originalType.
+            items.push({
+                originalType: action,
+                type: action === "COMMENT" ? "comment.received" : "unknown",
+            });
+        }
+    if (items.length === 0)
+        items.push({ originalType: kind, type: "unknown" });
+    return {
+        items,
+        accountIds,
+        data: payload,
+        occurredAt: lastModifiedAt === undefined ? undefined : new Date(lastModifiedAt).toISOString(),
+    };
+}
+function tiktokEventType(event) {
+    if (event === "authorization.removed")
+        return "account.updated";
+    if (event.startsWith("post.publish.") ||
+        event === "video.upload.failed" ||
+        event === "video.publish.completed")
+        return "publication.updated";
+    return "unknown";
+}
+function decodeTikTok(payload) {
+    const event = string(payload["event"]);
+    const createTime = payload["create_time"];
+    const rawContent = payload["content"];
+    // TikTok documents `content` as a serialized JSON object. Anything else is malformed;
+    // parse and object errors fall through to decodePlatformWebhook's invalid_input.
+    const content = rawContent === undefined ? undefined : object(parseJson(string(rawContent)));
+    const publishId = content === undefined ? undefined : optionalString(content["publish_id"]);
+    const openId = optionalString(payload["user_openid"]);
+    return {
+        items: [{ originalType: event, type: tiktokEventType(event) }],
+        accountIds: openId ? [openId] : [],
+        data: content === undefined ? payload : { ...payload, content },
+        backendRecordId: event.startsWith("post.publish.") ? publishId : undefined,
+        occurredAt: isFiniteNumber(createTime) && Number.isSafeInteger(createTime) && createTime > 0
+            ? new Date(createTime * 1000).toISOString()
+            : undefined,
+    };
+}
+function decodeDelivery(platform, text) {
+    if (platform === "youtube")
+        return decodeYouTube(text);
+    const payload = object(parseJson(text));
+    if (platform === "instagram")
+        return decodeInstagram(payload);
+    if (platform === "threads")
+        return decodeThreads(payload);
+    if (platform === "x")
+        return decodeX(payload);
+    if (platform === "linkedin")
+        return decodeLinkedIn(payload);
+    return decodeTikTok(payload);
+}
+/**
+ * Decode a verified direct-platform delivery into one normalized event. A single
+ * delivery can batch several notifications (Meta batches up to 1000 updates); the
+ * event keeps them all in `data` and reports a specific `type` only when every
+ * notification maps to the same type. None of these platforms sends a delivery ID,
+ * so identity is always an exact-body digest.
+ */
+export async function decodePlatformWebhook(input) {
+    const bytes = checkedBytes(input.body, input.maxBytes ?? defaultMaxBytes);
+    let delivery;
+    try {
+        delivery = decodeDelivery(input.platform, new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch (error) {
+        if (error instanceof SocialError)
+            throw error;
+        malformed(input.platform);
+    }
+    const types = [...new Set(delivery.items.map((item) => item.type))];
+    const originalTypes = [...new Set(delivery.items.map((item) => item.originalType))];
+    const cleaned = cleanObject(delivery.data);
+    const id = Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const event = {
+        version: 1,
+        id,
+        identity: "body-digest",
+        backend: input.backend,
+        provider: input.platform,
+        type: types.length === 1 && types[0] !== undefined ? types[0] : "unknown",
+        originalType: originalTypes.length === 0 ? "unknown" : originalTypes.join(","),
+        receivedAt: input.receivedAt ?? new Date().toISOString(),
+        accountIds: [...new Set(delivery.accountIds)],
+        data: cleaned,
+    };
+    const withRecord = delivery.backendRecordId === undefined
+        ? event
+        : { ...event, backendRecordId: delivery.backendRecordId };
+    return delivery.occurredAt === undefined
+        ? withRecord
+        : { ...withRecord, occurredAt: delivery.occurredAt };
+}