comisai 1.0.45 → 1.0.46

package/node_modules/@comis/channels/dist/msteams/credential-validator.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams Credential Validator: fail-fast guard that the bot
+ * credentials required to authenticate the adapter are present.
+ *
+ * Synchronous, transport-free, and secret-safe — it verifies appId and tenantId
+ * are non-empty plus the per-mode credential the configured authMode requires
+ * (secret → appPassword, certificate → certPath, managedIdentity →
+ * managedIdentityClientId), naming any missing field in the error, never the
+ * secret value itself. Live token-mint reachability is a separate operational
+ * probe and is intentionally out of scope here.
+ *
+ * @module
+ */
+import { ok, err } from "@comis/shared";
+/** A credential is missing when it is absent or all-whitespace. */
+function isBlank(value) {
+    return !value || value.trim() === "";
+}
+/**
+ * Verify the Microsoft Teams bot credentials required for the configured mode
+ * are present. appId + tenantId are always required; the third credential is
+ * authMode-branched (secret → appPassword, certificate → certPath,
+ * managedIdentity → managedIdentityClientId).
+ *
+ * @param opts.authMode - Credential mode (default "secret")
+ * @param opts.appId - Bot application (client) id
+ * @param opts.appPassword - Bot application secret (never named by value; secret mode)
+ * @param opts.tenantId - Single-tenant directory id
+ * @param opts.certPath - Certificate path (certificate mode)
+ * @param opts.managedIdentityClientId - Managed-identity client id (managed-identity mode)
+ * @returns ok when all required fields are non-empty; err naming the first missing field
+ */
+export function validateMsTeamsCredentials(opts) {
+    if (isBlank(opts.appId)) {
+        return err(new Error("Teams credentials invalid: appId must not be empty"));
+    }
+    if (isBlank(opts.tenantId)) {
+        return err(new Error("Teams credentials invalid: tenantId must not be empty"));
+    }
+    const authMode = opts.authMode ?? "secret";
+    if (authMode === "certificate") {
+        if (isBlank(opts.certPath)) {
+            return err(new Error("Teams credentials invalid: certPath must not be empty in certificate mode"));
+        }
+    }
+    else if (authMode === "managedIdentity") {
+        if (isBlank(opts.managedIdentityClientId)) {
+            return err(new Error("Teams credentials invalid: managedIdentityClientId must not be empty in managed-identity mode"));
+        }
+    }
+    else if (isBlank(opts.appPassword)) {
+        return err(new Error("Teams credentials invalid: appPassword must not be empty"));
+    }
+    return ok(undefined);
+}

package/node_modules/@comis/channels/dist/msteams/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Microsoft Teams error taxonomy: a pure classifier that maps a Bot Framework
+ * REST / token-endpoint HTTP status (or a transport-level failure) onto the
+ * closed observability errorKind union, a retry disposition, and an
+ * operator-actionable, origin-free hint.
+ *
+ * Deliberately minimal — the token mint and the outbound send path consult it
+ * to attach `errorKind` / `hint` on their failure branches. It reads only the
+ * numeric status; an optional cause is accepted for context but never rendered
+ * into the hint (a cause may carry secret-bearing text).
+ *
+ * @module
+ */
+/** The subset of the observability errorKind union this taxonomy emits. */
+export type MsTeamsErrorKind = "auth" | "platform" | "network" | "precondition" | "internal";
+/** A classified platform failure: kind, retry disposition, status, and hint. */
+export interface ClassifiedMsTeamsError {
+    /** The observability error kind. */
+    errorKind: MsTeamsErrorKind;
+    /** Whether retrying the same request could plausibly succeed. */
+    retryable: boolean;
+    /** The HTTP status, when a response was received. */
+    status?: number;
+    /** An operator-actionable next step. Never carries a secret. */
+    hint: string;
+}
+/**
+ * Classify a platform failure by its HTTP status.
+ *
+ * - `401` / `403` → `auth`, non-retryable — bad credentials, or not authorized
+ *   for the conversation/tenant; retrying without fixing the grant will not help.
+ * - `429` → `platform`, retryable — rate limited; back off then retry.
+ * - `>= 500` → `platform`, retryable — transient upstream error.
+ * - `undefined` → `network`, retryable — no response reached us (transport fault).
+ * - any other status (e.g. an unexpected 4xx) → `internal`, non-retryable — a
+ *   malformed request is our own defect, not a transient condition.
+ *
+ * @param status - The HTTP status of the response, or undefined for a
+ *   transport-level failure where no response was received.
+ * @param cause - The originating error, accepted for context but never
+ *   interpolated into the hint (it may carry secret-bearing text).
+ */
+export declare function classifyMsTeamsError(status: number | undefined, cause?: unknown): ClassifiedMsTeamsError;

package/node_modules/@comis/channels/dist/msteams/errors.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams error taxonomy: a pure classifier that maps a Bot Framework
+ * REST / token-endpoint HTTP status (or a transport-level failure) onto the
+ * closed observability errorKind union, a retry disposition, and an
+ * operator-actionable, origin-free hint.
+ *
+ * Deliberately minimal — the token mint and the outbound send path consult it
+ * to attach `errorKind` / `hint` on their failure branches. It reads only the
+ * numeric status; an optional cause is accepted for context but never rendered
+ * into the hint (a cause may carry secret-bearing text).
+ *
+ * @module
+ */
+/**
+ * Classify a platform failure by its HTTP status.
+ *
+ * - `401` / `403` → `auth`, non-retryable — bad credentials, or not authorized
+ *   for the conversation/tenant; retrying without fixing the grant will not help.
+ * - `429` → `platform`, retryable — rate limited; back off then retry.
+ * - `>= 500` → `platform`, retryable — transient upstream error.
+ * - `undefined` → `network`, retryable — no response reached us (transport fault).
+ * - any other status (e.g. an unexpected 4xx) → `internal`, non-retryable — a
+ *   malformed request is our own defect, not a transient condition.
+ *
+ * @param status - The HTTP status of the response, or undefined for a
+ *   transport-level failure where no response was received.
+ * @param cause - The originating error, accepted for context but never
+ *   interpolated into the hint (it may carry secret-bearing text).
+ */
+export function classifyMsTeamsError(status, cause) {
+    // `cause` is intentionally not read into the hint: it may carry secrets.
+    void cause;
+    if (status === undefined) {
+        return {
+            errorKind: "network",
+            retryable: true,
+            hint: "Check outbound connectivity to the identity and connector endpoints, then retry",
+        };
+    }
+    if (status === 401 || status === 403) {
+        return {
+            errorKind: "auth",
+            retryable: false,
+            status,
+            hint: "Verify the bot app id, password and tenant, and that the bot is authorized for this conversation",
+        };
+    }
+    if (status === 429) {
+        return {
+            errorKind: "platform",
+            retryable: true,
+            status,
+            hint: "Rate limited — back off and retry after the indicated window",
+        };
+    }
+    if (status >= 500) {
+        return {
+            errorKind: "platform",
+            retryable: true,
+            status,
+            hint: "Upstream service error — retry with backoff",
+        };
+    }
+    return {
+        errorKind: "internal",
+        retryable: false,
+        status,
+        hint: "Unexpected response status — inspect the request shape and payload",
+    };
+}

package/node_modules/@comis/channels/dist/msteams/mentions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Microsoft Teams @-mention helpers — pure and transport-free.
+ *
+ * Two directions:
+ *
+ * - INBOUND {@link detectBotMention}: is the bot itself @-mentioned? A mention
+ *   entity whose `mentioned.id` equals the activity recipient id. (The inbound
+ *   `<at>…</at>` strip lives in the message-mapper's plain-text pass — this file
+ *   only decides whether the bot was addressed.)
+ * - OUTBOUND {@link buildMentionEntities}: turn `@[Name](id)` markup into the
+ *   Teams `<at>Name</at>` tag + the paired `entities[]` mention element — but
+ *   ONLY when `id` matches an anchored AAD directory GUID or a `28:<guid>` bot
+ *   id. An id that matches neither is left as plain text so a code/doc sample
+ *   that merely looks like a mention can never become a real one.
+ *
+ * @module
+ */
+/** A Teams `entities[]` mention element paired with an `<at>…</at>` tag in the body. */
+export interface TeamsMentionEntity {
+    type: "mention";
+    /** Must match the `<at>Name</at>` tag verbatim in the activity text. */
+    text: string;
+    mentioned: {
+        id: string;
+        name: string;
+    };
+}
+/** The outbound-mention build result: rewritten text + the entities to attach. */
+export interface BuiltMention {
+    text: string;
+    entities: TeamsMentionEntity[];
+}
+/**
+ * True when an inbound activity @-mentions the bot itself — a `mention` entity
+ * whose target equals the recipient id.
+ *
+ * An absent recipient id yields false so a mention entity carrying no target
+ * (`mentioned` undefined) can never be misread as addressing the bot.
+ */
+export declare function detectBotMention(entities: ReadonlyArray<{
+    type: string;
+    mentioned?: {
+        id: string;
+    };
+}> | undefined, recipientId: string | undefined): boolean;
+/**
+ * Rewrite `@[Name](id)` markup into Teams `<at>Name</at>` tags and collect the
+ * paired mention entities — gated on {@link isMentionableId}. Markup whose id
+ * matches neither shape is returned unchanged with no entity (the false-mention
+ * control): a `@`-looking code or documentation sample stays literal text.
+ */
+export declare function buildMentionEntities(markup: string): BuiltMention;

package/node_modules/@comis/channels/dist/msteams/mentions.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams @-mention helpers — pure and transport-free.
+ *
+ * Two directions:
+ *
+ * - INBOUND {@link detectBotMention}: is the bot itself @-mentioned? A mention
+ *   entity whose `mentioned.id` equals the activity recipient id. (The inbound
+ *   `<at>…</at>` strip lives in the message-mapper's plain-text pass — this file
+ *   only decides whether the bot was addressed.)
+ * - OUTBOUND {@link buildMentionEntities}: turn `@[Name](id)` markup into the
+ *   Teams `<at>Name</at>` tag + the paired `entities[]` mention element — but
+ *   ONLY when `id` matches an anchored AAD directory GUID or a `28:<guid>` bot
+ *   id. An id that matches neither is left as plain text so a code/doc sample
+ *   that merely looks like a mention can never become a real one.
+ *
+ * @module
+ */
+/** Anchored AAD directory object GUID: 8-4-4-4-12 hex groups. */
+const AAD_GUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** Anchored Bot Framework bot id: the `28:` prefix followed by a hex/dash guid. */
+const BOT_ID_RE = /^28:[0-9a-fA-F-]+$/;
+/** `@[Display Name](id)` mention markup — name excludes `]`, id excludes `)`. */
+const MENTION_MARKUP_RE = /@\[([^\]]+)\]\(([^)]+)\)/g;
+/**
+ * True when an inbound activity @-mentions the bot itself — a `mention` entity
+ * whose target equals the recipient id.
+ *
+ * An absent recipient id yields false so a mention entity carrying no target
+ * (`mentioned` undefined) can never be misread as addressing the bot.
+ */
+export function detectBotMention(entities, recipientId) {
+    if (!recipientId)
+        return false;
+    return entities?.some((e) => e.type === "mention" && e.mentioned?.id === recipientId) ?? false;
+}
+/** True when an id is a shape a real outbound mention may reference. */
+function isMentionableId(id) {
+    return AAD_GUID_RE.test(id) || BOT_ID_RE.test(id);
+}
+/**
+ * Rewrite `@[Name](id)` markup into Teams `<at>Name</at>` tags and collect the
+ * paired mention entities — gated on {@link isMentionableId}. Markup whose id
+ * matches neither shape is returned unchanged with no entity (the false-mention
+ * control): a `@`-looking code or documentation sample stays literal text.
+ */
+export function buildMentionEntities(markup) {
+    const entities = [];
+    const text = markup.replace(MENTION_MARKUP_RE, (whole, name, id) => {
+        if (!isMentionableId(id))
+            return whole;
+        const tag = `<at>${name}</at>`;
+        entities.push({ type: "mention", text: tag, mentioned: { id, name } });
+        return tag;
+    });
+    return { text, entities };
+}

package/node_modules/@comis/channels/dist/msteams/message-mapper.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Microsoft Teams Message Mapper: converts a Bot Framework activity into a
+ * NormalizedMessage.
+ *
+ * Pure and transport-free — the adapter hands a plain activity object here so
+ * the mapping is unit-testable without any HTTP layer. It is the single point
+ * that decides the routing identity the inbound path keys on:
+ *
+ * - conversationType personal|groupChat|channel -> chatType dm|group|channel
+ * - conversation.id ";messageid=…" reply suffix -> stripped channelId
+ * - from.aadObjectId (stable directory id) preferred over from.id for senderId
+ * - <at>…</at> mention markup stripped so the text is faithful plain text
+ *
+ * Returns null for non-message activities (conversationUpdate, messageReaction,
+ * …) so the adapter early-returns on them.
+ *
+ * @module
+ */
+import type { NormalizedMessage } from "@comis/core";
+/**
+ * Minimal Bot Framework activity shape — only the fields the inbound path
+ * reads. Deliberately loose: the connector sends many more fields we ignore.
+ */
+export interface TeamsActivity {
+    /** Activity kind: "message" | "conversationUpdate" | "messageReaction" | … */
+    type: string;
+    /** Activity id — the reply/edit/delete target. */
+    id?: string;
+    text?: string;
+    conversation: {
+        id: string;
+        conversationType?: "personal" | "groupChat" | "channel";
+        tenantId?: string;
+    };
+    from?: {
+        id: string;
+        aadObjectId?: string;
+        name?: string;
+    };
+    recipient?: {
+        id: string;
+        name?: string;
+    };
+    serviceUrl?: string;
+    replyToId?: string;
+    channelData?: {
+        tenant?: {
+            id?: string;
+        };
+    };
+    entities?: Array<{
+        type: string;
+        mentioned?: {
+            id: string;
+        };
+        text?: string;
+    }>;
+    /** Invoke sub-kind, e.g. "adaptiveCard/action" for a card-action click. */
+    name?: string;
+    /**
+     * Card-action invoke payload. Client-controllable — read only on an invoke,
+     * and only for the rendered `verb` and the signed callback `data.cb`; no
+     * identity is ever sourced from here.
+     */
+    value?: {
+        action?: {
+            verb?: string;
+            data?: {
+                cb?: string;
+            };
+        };
+    };
+    /**
+     * Inbound file/media attachments. `contentUrl` is a hosted-content link that
+     * needs the Connector Bearer at fetch time; `content.downloadUrl` is a
+     * pre-authed SharePoint link that carries no header and 302-redirects to
+     * storage. The mapper never fetches these — it only rewrites each to the
+     * custom `msteams-file://` scheme so the composite routes deferred,
+     * SSRF-guarded resolution to the Teams resolver rather than the https
+     * fallback.
+     */
+    attachments?: Array<{
+        contentType: string;
+        contentUrl?: string;
+        name?: string;
+        content?: {
+            downloadUrl?: string;
+        };
+    }>;
+}
+/**
+ * Strip a trailing ";messageid=…" suffix from a conversation id.
+ *
+ * Channel replies arrive with the conversation id carrying the parent message
+ * id (e.g. "19:abc@thread.tacv2;messageid=1700000000000"); the routing key is
+ * the bare conversation id, so the suffix is removed.
+ */
+export declare function stripMessageIdSuffix(conversationId: string): string;
+/**
+ * The thread root to persist for a conversation-reference capture: the
+ * channel/group thread parent, or undefined for a 1:1 DM (which is always
+ * top-level). Shared by the inbound message capture (via the mapped
+ * `msteamsThreadId` metadata) and the inbound reaction capture so both key the
+ * same routing tuple and neither clobbers the other's stored thread root.
+ */
+export declare function resolveCaptureThreadId(activity: TeamsActivity): string | undefined;
+/**
+ * Map a Bot Framework activity to a NormalizedMessage.
+ *
+ * @param activity - A Bot Framework inbound activity
+ * @returns A NormalizedMessage for message activities; null otherwise
+ */
+export declare function mapMsTeamsActivityToNormalized(activity: TeamsActivity): NormalizedMessage | null;

package/node_modules/@comis/channels/dist/msteams/message-mapper.js

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams Message Mapper: converts a Bot Framework activity into a
+ * NormalizedMessage.
+ *
+ * Pure and transport-free — the adapter hands a plain activity object here so
+ * the mapping is unit-testable without any HTTP layer. It is the single point
+ * that decides the routing identity the inbound path keys on:
+ *
+ * - conversationType personal|groupChat|channel -> chatType dm|group|channel
+ * - conversation.id ";messageid=…" reply suffix -> stripped channelId
+ * - from.aadObjectId (stable directory id) preferred over from.id for senderId
+ * - <at>…</at> mention markup stripped so the text is faithful plain text
+ *
+ * Returns null for non-message activities (conversationUpdate, messageReaction,
+ * …) so the adapter early-returns on them.
+ *
+ * @module
+ */
+import { systemNowMs } from "@comis/core";
+import { randomUUID } from "node:crypto";
+import { detectBotMention } from "./mentions.js";
+import { mimeToAttachmentType } from "../shared/media-utils.js";
+/** The reply-suffix marker that carries the parent-message id in a channel conversation id. */
+const MESSAGE_ID_MARKER = ";messageid=";
+/**
+ * Strip a trailing ";messageid=…" suffix from a conversation id.
+ *
+ * Channel replies arrive with the conversation id carrying the parent message
+ * id (e.g. "19:abc@thread.tacv2;messageid=1700000000000"); the routing key is
+ * the bare conversation id, so the suffix is removed.
+ */
+export function stripMessageIdSuffix(conversationId) {
+    const idx = conversationId.indexOf(MESSAGE_ID_MARKER);
+    return idx >= 0 ? conversationId.slice(0, idx) : conversationId;
+}
+/**
+ * Extract the thread root of a channel/group activity: the parent-message id
+ * carried in the conversation id's ";messageid=…" suffix (preferred), else the
+ * replyToId. Returns undefined when neither is present. Surfaced under a
+ * Teams-specific metadata key so the session-key path can isolate one thread
+ * per session without affecting any other channel's mapping.
+ */
+function extractThreadRoot(activity) {
+    const convId = activity.conversation.id;
+    const idx = convId.indexOf(MESSAGE_ID_MARKER);
+    if (idx >= 0)
+        return convId.slice(idx + MESSAGE_ID_MARKER.length);
+    return activity.replyToId;
+}
+/**
+ * Reduce Teams message text to plain text: drop <at>…</at> mention spans, strip
+ * any remaining HTML tags, and collapse whitespace. A regex pass suffices for
+ * the text this path carries; richer HTML (tables, links) would extend this.
+ */
+function toPlainText(raw) {
+    if (!raw)
+        return "";
+    return raw
+        .replace(/<at\b[^>]*>.*?<\/at>/gi, "")
+        .replace(/<[^>]+>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Derive the normalized chatType from the Bot Framework conversationType.
+ * Unknown/absent types default to "channel".
+ */
+function toChatType(conversationType) {
+    switch (conversationType) {
+        case "personal":
+            return "dm";
+        case "groupChat":
+            return "group";
+        case "channel":
+            return "channel";
+        default:
+            return "channel";
+    }
+}
+/**
+ * The thread root to persist for a conversation-reference capture: the
+ * channel/group thread parent, or undefined for a 1:1 DM (which is always
+ * top-level). Shared by the inbound message capture (via the mapped
+ * `msteamsThreadId` metadata) and the inbound reaction capture so both key the
+ * same routing tuple and neither clobbers the other's stored thread root.
+ */
+export function resolveCaptureThreadId(activity) {
+    if (toChatType(activity.conversation.conversationType) === "dm")
+        return undefined;
+    return extractThreadRoot(activity);
+}
+/**
+ * Map a Bot Framework activity to a NormalizedMessage.
+ *
+ * @param activity - A Bot Framework inbound activity
+ * @returns A NormalizedMessage for message activities; null otherwise
+ */
+export function mapMsTeamsActivityToNormalized(activity) {
+    if (activity.type !== "message")
+        return null;
+    const chatType = toChatType(activity.conversation.conversationType);
+    const metadata = {};
+    if (activity.id !== undefined)
+        metadata.teamsActivityId = activity.id;
+    if (activity.serviceUrl !== undefined)
+        metadata.serviceUrl = activity.serviceUrl;
+    const tenantId = activity.channelData?.tenant?.id ?? activity.conversation.tenantId;
+    if (tenantId !== undefined)
+        metadata.tenantId = tenantId;
+    if (activity.replyToId !== undefined)
+        metadata.replyToId = activity.replyToId;
+    // Thread isolation is a channel/group concern; a 1:1 DM has no thread root.
+    const threadRoot = resolveCaptureThreadId(activity);
+    if (threadRoot !== undefined)
+        metadata.msteamsThreadId = threadRoot;
+    metadata.mentionedBot = detectBotMention(activity.entities, activity.recipient?.id);
+    // Rewrite each attachment to the custom `msteams-file://` scheme carrying the
+    // encodeURIComponent-wrapped real URL. encodeURIComponent guarantees no bare
+    // "://" inside the payload, so the composite resolver's scheme split sees
+    // exactly `msteams-file` and routes to the Teams resolver (never the https
+    // fallback). The pre-authed `content.downloadUrl` is preferred over the
+    // hosted-content `contentUrl`; an attachment with no fetchable URL is dropped.
+    const attachments = (activity.attachments ?? []).flatMap((att) => {
+        const realUrl = att.content?.downloadUrl ?? att.contentUrl;
+        if (realUrl == null || realUrl.length === 0)
+            return [];
+        return [
+            {
+                type: mimeToAttachmentType(att.contentType),
+                url: `msteams-file://${encodeURIComponent(realUrl)}`,
+                ...(att.contentType != null && { mimeType: att.contentType }),
+                ...(att.name != null && { fileName: att.name }),
+            },
+        ];
+    });
+    return {
+        id: randomUUID(),
+        channelId: stripMessageIdSuffix(activity.conversation.id),
+        channelType: "msteams",
+        senderId: activity.from?.aadObjectId ?? activity.from?.id ?? "unknown",
+        text: toPlainText(activity.text),
+        timestamp: systemNowMs(),
+        attachments,
+        chatType,
+        metadata,
+    };
+}

package/node_modules/@comis/channels/dist/msteams/msteams-actions.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Microsoft Teams card-action normalizer.
+ *
+ * Turns a Bot Framework "adaptiveCard/action" invoke into a button-callback
+ * NormalizedMessage the inbound approval path already understands — or drops it
+ * (returning the reason) when the activity is not a well-formed, rendered card
+ * action, so the adapter can make the security-relevant rejects observable.
+ *
+ * Two trust decisions live here, and only these two:
+ *
+ *  - the clicker identity is sourced ONLY from the verified activity
+ *    (`from.aadObjectId`, established when the ingress validated the Bot
+ *    Framework JWT) — never from the client-controllable `value.action.data`; and
+ *  - the incoming `verb` must be one this bot actually renders
+ *    (`RENDERED_VERBS`) — an unknown verb never becomes a message.
+ *
+ * What this module deliberately does NOT do: it never authorizes the clicker
+ * (default-deny is the existing allowFrom gate on the verified senderId) and
+ * never verifies the callback signature (the downstream router's constant-time
+ * HMAC / session / expiry / replay checks own that). The signed `data.cb` is
+ * passed through opaquely as `metadata.callbackData`.
+ *
+ * @module
+ */
+import type { NormalizedMessage } from "@comis/core";
+import { type TeamsActivity } from "./message-mapper.js";
+/**
+ * The verb the approval card renders on its buttons. Shared by the renderer
+ * that stamps it onto the card and the validator here, so the two never drift.
+ */
+export declare const MSTEAMS_APPROVAL_VERB = "comis.approval.resolve";
+/**
+ * The CLOSED set of verbs this bot actually renders onto cards. A card-action
+ * invoke carrying any other verb is dropped before it becomes a message — a
+ * click cannot invoke a method that was never rendered.
+ */
+export declare const RENDERED_VERBS: readonly string[];
+/**
+ * Why a card-action invoke did not become a message.
+ *
+ *  - `ignored`: not an adaptiveCard/action invoke (a ping or a non-card invoke)
+ *    — a benign, expected drop the caller logs nowhere.
+ *  - `unrendered-verb`: the verb is outside {@link RENDERED_VERBS} — an arbitrary
+ *    method a click could never have rendered (an attacker-crafted probe).
+ *  - `missing-callback`: no signed `data.cb` — a malformed card action.
+ *  - `missing-clicker`: no verified `from.aadObjectId` — the clicker cannot be
+ *    authorized (e.g. a guest/federated identity the tenant did not populate).
+ *
+ * The last three are security-relevant rejects the caller must make observable;
+ * `ignored` is not. The normalizer stays pure — it names the reason, and the
+ * adapter owns the §2.7 logging (as it does for the message and reaction drops).
+ */
+export type CardActionDropReason = "ignored" | "unrendered-verb" | "missing-callback" | "missing-clicker";
+/**
+ * The outcome of normalizing a card-action invoke: either the button-callback
+ * message, or a drop carrying the {@link CardActionDropReason} so the caller can
+ * log the specific reject class. Discriminate on `message === null`.
+ */
+export type CardActionResult = {
+    readonly message: NormalizedMessage;
+    readonly reason?: undefined;
+} | {
+    readonly message: null;
+    readonly reason: CardActionDropReason;
+};
+/**
+ * Normalize a Bot Framework card-action invoke into a button-callback message.
+ *
+ * Returns `{ message }` on success, or `{ message: null, reason }` when the
+ * activity is not an adaptiveCard/action invoke (`ignored`), the verb is not in
+ * {@link RENDERED_VERBS} (`unrendered-verb`), the signed callback is missing
+ * (`missing-callback`), or `from.aadObjectId` is absent (`missing-clicker`).
+ * The reason lets the caller log the security-relevant rejects per §2.7 while
+ * this function stays a pure mapper.
+ *
+ * @param activity - A Bot Framework invoke activity (already JWT-validated)
+ * @returns A button-callback message, or a drop carrying its reason
+ */
+export declare function normalizeCardAction(activity: TeamsActivity): CardActionResult;