comisai 1.0.45 → 1.0.46

package/node_modules/@comis/channels/dist/msteams/msteams-connector.js

@@ -0,0 +1,414 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams Bot Framework Connector transport.
+ *
+ * The REST mechanics the adapter drives — path-safety guards, the cached-token
+ * PUT/DELETE activity mutations, and the typing keepalive — factored out so the
+ * adapter stays a lean controller (it resolves the routing context + owns the
+ * handlers; this module owns the wire). Every call reuses the shared token
+ * provider, the `classifyMsTeamsError` failure classifier and the
+ * `encodeURIComponent` path-safety; none of it touches adapter state.
+ *
+ * Security-relevant guards live here because this is where ids/serviceUrls are
+ * interpolated into the REST path (T-8) and where the bearer token is emitted
+ * (T-3 host allowlist / T-5 no-log).
+ *
+ * @module
+ */
+import { err, fromPromise, ok, tryCatch } from "@comis/shared";
+import { classifyMsTeamsError } from "./errors.js";
+import { buildMentionEntities } from "./mentions.js";
+// ---------------------------------------------------------------------------
+// Path safety (T-8 / T-3)
+// ---------------------------------------------------------------------------
+/** True if the id carries an ASCII control character (never valid, always dropped). */
+function hasControlChar(id) {
+    for (let i = 0; i < id.length; i++) {
+        const code = id.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * Reject a conversation/activity id that is empty, `..`-escaping, or carries a
+ * control character. The charset is otherwise unconstrained: the id is
+ * URL-encoded before it is interpolated into the REST path, so path separators
+ * (standard base64 `@thread.v2` ids carry `/`) are transported safely rather
+ * than false-rejected.
+ */
+export function isSafeConversationId(id) {
+    return id.length > 0 && !id.includes("..") && !hasControlChar(id);
+}
+/**
+ * Bot Framework Connector service hosts, keyed by deployment cloud. A minted
+ * Connector bearer token is only ever transmitted to the EXACT host for the
+ * configured cloud, so an inbound activity (or a stored reference) bearing a
+ * hostile or cross-cloud serviceUrl cannot exfiltrate the token to an arbitrary
+ * origin. Exact hosts, never suffixes: a `*.trafficmanager.net` match would admit
+ * any Traffic Manager profile an attacker can register.
+ */
+const CLOUD_CONNECTOR_HOSTS = {
+    public: ["smba.trafficmanager.net"],
+    china: ["botframework.azure.cn"],
+};
+/**
+ * A send target is safe only over https, free of a `..` traversal segment, and
+ * hosted on the EXACT Bot Framework Connector service host for the configured
+ * cloud — so the bearer token is never sent to an arbitrary or cross-cloud origin.
+ */
+export function isSafeServiceUrl(serviceUrl, cloud = "public") {
+    if (serviceUrl.includes(".."))
+        return false;
+    const parsed = tryCatch(() => new URL(serviceUrl));
+    if (!parsed.ok || parsed.value.protocol !== "https:")
+        return false;
+    const host = parsed.value.hostname.toLowerCase();
+    // eslint-disable-next-line security/detect-object-injection -- cloud is a closed "public"|"china" union matching the literal record's keys
+    return CLOUD_CONNECTOR_HOSTS[cloud].includes(host);
+}
+/**
+ * POST a fully-built activity to the Bot Framework Connector create-activity
+ * endpoint. The single wire path shared by the adapter's text send and its
+ * attachment send: it runs the id- and serviceUrl-safety gates (T-8/T-3) BEFORE
+ * minting the bearer, so an unsafe target never triggers a token mint or a fetch;
+ * classifies a non-2xx (or a transport fault) through the shared taxonomy; and
+ * never places the token or the activity body in a structured log field (T-5).
+ * Returns the created activity id on success. Holds no adapter state — the caller
+ * folds the Result into its health tracking.
+ */
+export async function postConnectorActivity(params) {
+    const { serviceUrl, conversationId, activityBody, tokens, logger, now } = params;
+    const startedAt = now();
+    // Path-safety gate: validate the interpolated id before any store lookup or
+    // REST path build — a traversal id must never reach a fetch.
+    if (!isSafeConversationId(conversationId)) {
+        logger.warn({
+            channelType: "msteams",
+            hint: "Reject the conversation id: it must be free of path separators and '..'",
+            errorKind: "precondition",
+        }, "Connector send blocked: unsafe conversation id");
+        return err(new Error("unsafe conversation id"));
+    }
+    if (!isSafeServiceUrl(serviceUrl, params.cloud ?? "public")) {
+        logger.warn({
+            channelType: "msteams",
+            hint: "Reject the serviceUrl: it must be the https Bot Framework Connector host for the configured cloud, free of '..'",
+            errorKind: "precondition",
+        }, "Connector send blocked: unsafe service url");
+        return err(new Error("unsafe service url"));
+    }
+    const tok = await tokens.getToken();
+    if (!tok.ok)
+        return err(tok.error);
+    const url = `${serviceUrl}v3/conversations/${encodeURIComponent(conversationId)}/activities`;
+    const responded = await fromPromise((params.fetchImpl ?? fetch)(url, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${tok.value}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(activityBody),
+    }));
+    if (!responded.ok) {
+        // No response reached us: a transport-level fault (undefined status).
+        const classified = classifyMsTeamsError(undefined, responded.error);
+        logger.warn({
+            channelType: "msteams",
+            hint: classified.hint,
+            errorKind: classified.errorKind,
+        }, "Connector send failed: no response from the connector");
+        return err(responded.error);
+    }
+    const res = responded.value;
+    if (!res.ok) {
+        const classified = classifyMsTeamsError(res.status);
+        const retryAfter = parseRetryAfterSeconds(res);
+        logger.warn({
+            channelType: "msteams",
+            status: res.status,
+            hint: classified.hint,
+            errorKind: classified.errorKind,
+        }, "Connector send failed: connector returned an error status");
+        // Structural status (+ Retry-After on a 429) so the bounded-retry executor can
+        // classify the disposition and time the backoff off the error alone.
+        return err(connectorRestError(res.status, retryAfter));
+    }
+    const parsed = await fromPromise(res.json());
+    const sentId = parsed.ok && typeof parsed.value.id === "string" ? parsed.value.id : "sent";
+    logger.info({
+        step: "channels-outbound",
+        channelType: "msteams",
+        messageId: sentId,
+        chatId: conversationId,
+        durationMs: now() - startedAt,
+    }, "Outbound message");
+    return ok(sentId);
+}
+/** Build a {@link ConnectorRestError} carrying the status (+ retryAfter on a 429). */
+function connectorRestError(status, retryAfter) {
+    const error = new Error(`connector request returned status ${status}`);
+    error.status = status;
+    if (retryAfter !== undefined)
+        error.retryAfter = retryAfter;
+    return error;
+}
+/** Read the integer `Retry-After` seconds off a Connector response, when present. */
+function parseRetryAfterSeconds(res) {
+    const raw = res.headers?.get?.("retry-after");
+    if (typeof raw !== "string")
+        return undefined;
+    const seconds = Number.parseInt(raw, 10);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+// ---------------------------------------------------------------------------
+// Bounded send retry (429-only — a resend must never duplicate a create)
+// ---------------------------------------------------------------------------
+/** Retries the send makes on top of the first attempt before surfacing the failure. */
+const MAX_RETRIES = 4;
+/** Exponential-backoff base + ceiling for a retryable 5xx (a 429 uses its Retry-After). */
+const RETRY_BACKOFF_BASE_MS = 500;
+const RETRY_BACKOFF_CAP_MS = 8_000;
+/**
+ * Ceiling on a server-supplied `Retry-After`. The value is operator-untrusted, so
+ * a large or hostile `Retry-After` (e.g. 86400s) is clamped rather than awaited
+ * verbatim — otherwise the outbound send would park pending for hours, stalling
+ * that delivery-pipeline slot, and could repeat up to {@link MAX_RETRIES} times.
+ */
+const RETRY_AFTER_CAP_MS = 60_000;
+/** Read the structural HTTP status a Connector REST error carries (absent on a transport fault). */
+function connectorErrorStatus(error) {
+    const status = error.status;
+    return typeof status === "number" ? status : undefined;
+}
+/** Read the structural Retry-After seconds a 429 Connector error carries, when present. */
+function connectorErrorRetryAfter(error) {
+    const retryAfter = error.retryAfter;
+    return typeof retryAfter === "number" ? retryAfter : undefined;
+}
+/**
+ * Send an activity with a bounded retry that engages ONLY on a 429 (rate limited,
+ * so the activity was definitively NOT processed): it backs off the capped
+ * Retry-After, or capped exponential backoff when the header is absent. Every
+ * other failure surfaces on the FIRST attempt — a status-less transport fault OR
+ * a 5xx (a gateway-timeout class that can land AFTER the activity was created)
+ * may already have created the activity, and create-activity is non-idempotent
+ * (no client idempotency key; the outward-send ledger dedups per send call, not
+ * per HTTP attempt), so a resend would duplicate the message. The send-safety
+ * axis is deliberately narrower than the classifier's transience axis, which
+ * still marks 5xx/network retryable for a caller that CAN safely retry. The
+ * backoff always runs on the injected {@link TimerPort}, never a raw timer, and
+ * total retries are capped at {@link MAX_RETRIES}. This is the send entry point
+ * the adapter drives.
+ */
+export async function postConnectorActivityWithRetry(params, retryDeps = {}) {
+    const { timer } = retryDeps;
+    for (let attempt = 0;; attempt++) {
+        const result = await postConnectorActivity(params);
+        if (result.ok)
+            return result;
+        const status = connectorErrorStatus(result.error);
+        // Send-safety gate: create-activity is non-idempotent, so the ONLY status
+        // safe to resend is a 429 — rate limiting rejects it BEFORE the activity is
+        // processed, so it definitively did not land. A status-less transport fault
+        // OR a 5xx (which can arrive AFTER the activity was created) may already have
+        // landed; resending either would duplicate the message, so both surface here.
+        if (status !== 429 || attempt >= MAX_RETRIES || timer === undefined) {
+            return result;
+        }
+        const classified = classifyMsTeamsError(status);
+        const retryAfter = connectorErrorRetryAfter(result.error);
+        const delayMs = retryAfter !== undefined
+            ? Math.min(retryAfter * 1000, RETRY_AFTER_CAP_MS)
+            : Math.min(RETRY_BACKOFF_BASE_MS * 2 ** attempt, RETRY_BACKOFF_CAP_MS);
+        params.logger.debug({
+            step: "channels-outbound",
+            channelType: "msteams",
+            status,
+            attempt: attempt + 1,
+            durationMs: delayMs,
+            hint: classified.hint,
+            errorKind: classified.errorKind,
+        }, "Connector send retry scheduled after a retryable status");
+        await new Promise((resolve) => {
+            const handle = timer.setTimeout(() => resolve(), delayMs);
+            handle.unref();
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Typing keepalive tuning
+// ---------------------------------------------------------------------------
+/**
+ * A Bot Framework typing activity lapses after roughly half a minute, so the
+ * keepalive re-POSTs one every {@link TYPING_REFRESH_MS} to hold the indicator
+ * open. {@link TYPING_TTL_MS} caps the total keepalive lifetime so an un-stopped
+ * indicator (a missed stop signal) can never refresh forever;
+ * {@link MAX_TYPING_REFRESHES} expresses that cap as a refresh count so it holds
+ * regardless of the injected clock. Internal constants — not operator-tunable.
+ */
+const TYPING_REFRESH_MS = 8_000;
+const TYPING_TTL_MS = 600_000;
+const MAX_TYPING_REFRESHES = Math.ceil(TYPING_TTL_MS / TYPING_REFRESH_MS);
+/**
+ * Build the Connector transport over the injected token/fetch/timer. The
+ * edit/delete calls validate the interpolated ids + serviceUrl (T-8/T-3) before
+ * any fetch and return a {@link ConnectorRestError} on a non-2xx so the caller's
+ * edit-in-place renderer can classify it. State (health, lastError) stays with
+ * the adapter — these calls only return `Result`.
+ */
+export function createMsTeamsConnector(deps) {
+    let typingHandle;
+    let typingRefreshCount = 0;
+    async function mutate(method, op, serviceUrl, conversationId, messageId, text) {
+        const startedAt = deps.now();
+        // Path-safety gate: validate BOTH interpolated ids before building the path.
+        if (!isSafeConversationId(conversationId) || !isSafeConversationId(messageId)) {
+            deps.logger.warn({
+                channelType: "msteams",
+                op,
+                hint: "Reject the conversation/message id: it must be free of control chars and '..'",
+                errorKind: "precondition",
+            }, "Connector activity mutation blocked: unsafe id");
+            return err(new Error("unsafe activity id"));
+        }
+        if (!isSafeServiceUrl(serviceUrl, deps.cloud ?? "public")) {
+            deps.logger.warn({
+                channelType: "msteams",
+                op,
+                hint: "Reject the serviceUrl: it must be the https Bot Framework Connector host for the configured cloud, free of '..'",
+                errorKind: "precondition",
+            }, "Connector activity mutation blocked: unsafe service url");
+            return err(new Error("unsafe service url"));
+        }
+        const tok = await deps.tokens.getToken();
+        if (!tok.ok)
+            return err(tok.error);
+        const url = `${serviceUrl}v3/conversations/${encodeURIComponent(conversationId)}/activities/${encodeURIComponent(messageId)}`;
+        const init = {
+            method,
+            headers: {
+                authorization: `Bearer ${tok.value}`,
+                "content-type": "application/json",
+            },
+        };
+        if (text !== undefined) {
+            const built = buildMentionEntities(text);
+            const body = { type: "message", text: built.text };
+            if (built.entities.length > 0)
+                body.entities = built.entities;
+            init.body = JSON.stringify(body);
+        }
+        const responded = await fromPromise((deps.fetchImpl ?? fetch)(url, init));
+        if (!responded.ok) {
+            const classified = classifyMsTeamsError(undefined, responded.error);
+            deps.logger.warn({
+                channelType: "msteams",
+                op,
+                hint: classified.hint,
+                errorKind: classified.errorKind,
+            }, "Connector activity mutation failed: no response from the connector");
+            return err(responded.error);
+        }
+        const res = responded.value;
+        if (!res.ok) {
+            const classified = classifyMsTeamsError(res.status);
+            const retryAfter = parseRetryAfterSeconds(res);
+            deps.logger.warn({
+                channelType: "msteams",
+                op,
+                status: res.status,
+                hint: classified.hint,
+                errorKind: classified.errorKind,
+            }, "Connector activity mutation failed: connector returned an error status");
+            // Structural status so the edit-in-place renderer classifies (429/404/…).
+            return err(connectorRestError(res.status, retryAfter));
+        }
+        deps.logger.info({
+            step: "channels-outbound",
+            channelType: "msteams",
+            op,
+            messageId,
+            chatId: conversationId,
+            durationMs: deps.now() - startedAt,
+        }, "Outbound activity mutation");
+        return ok(undefined);
+    }
+    function stopTyping() {
+        if (typingHandle !== undefined && !typingHandle.cancelled)
+            typingHandle.cancel();
+        typingHandle = undefined;
+    }
+    /** POST a single {type:"typing"} activity (best-effort; failures log at DEBUG). */
+    async function postTyping(conversationId, serviceUrl) {
+        // Self-enforce the host allowlist on the wire path BEFORE the mint, exactly as
+        // postConnectorActivity/mutate do: the Connector bearer must never reach a
+        // non-Connector or cross-cloud host on ANY send path, so a future caller of
+        // startTyping cannot bypass the adapter-side check and leak the token.
+        if (!isSafeServiceUrl(serviceUrl, deps.cloud ?? "public")) {
+            deps.logger.warn({
+                channelType: "msteams",
+                hint: "Reject the serviceUrl: it must be the https Bot Framework Connector host for the configured cloud, free of '..'",
+                errorKind: "precondition",
+            }, "Typing keepalive blocked: unsafe service url");
+            return;
+        }
+        const tok = await deps.tokens.getToken();
+        if (!tok.ok)
+            return; // the token provider already logged its failure branch
+        const url = `${serviceUrl}v3/conversations/${encodeURIComponent(conversationId)}/activities`;
+        const responded = await fromPromise((deps.fetchImpl ?? fetch)(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${tok.value}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ type: "typing" }),
+        }));
+        if (!responded.ok) {
+            const classified = classifyMsTeamsError(undefined, responded.error);
+            deps.logger.debug({ channelType: "msteams", hint: classified.hint, errorKind: classified.errorKind }, "Typing keepalive post failed to reach the connector");
+            return;
+        }
+        if (!responded.value.ok) {
+            const classified = classifyMsTeamsError(responded.value.status);
+            deps.logger.debug({
+                channelType: "msteams",
+                status: responded.value.status,
+                hint: classified.hint,
+                errorKind: classified.errorKind,
+            }, "Typing keepalive post rejected by the connector");
+        }
+    }
+    function scheduleRefresh(conversationId, serviceUrl) {
+        const timer = deps.timer;
+        if (timer === undefined)
+            return;
+        if (typingRefreshCount >= MAX_TYPING_REFRESHES) {
+            // TTL backstop: stop rearming even without an explicit stopTyping.
+            stopTyping();
+            return;
+        }
+        const handle = timer.setTimeout(() => {
+            typingHandle = undefined;
+            typingRefreshCount += 1;
+            void postTyping(conversationId, serviceUrl);
+            scheduleRefresh(conversationId, serviceUrl);
+        }, TYPING_REFRESH_MS);
+        handle.unref();
+        typingHandle = handle;
+    }
+    function startTyping(conversationId, serviceUrl) {
+        // Idempotent restart: cancel any prior keepalive, POST now, schedule refreshes.
+        stopTyping();
+        typingRefreshCount = 0;
+        void postTyping(conversationId, serviceUrl);
+        scheduleRefresh(conversationId, serviceUrl);
+    }
+    return {
+        editActivity: (serviceUrl, conversationId, messageId, text) => mutate("PUT", "edit", serviceUrl, conversationId, messageId, text),
+        deleteActivity: (serviceUrl, conversationId, messageId) => mutate("DELETE", "delete", serviceUrl, conversationId, messageId),
+        startTyping,
+        stopTyping,
+    };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Microsoft Teams Channel Plugin: wraps the Teams adapter as a ChannelPluginPort
+ * with capability-parity metadata.
+ *
+ * The adapter implements inbound reactions, edit/delete, a typing keepalive and
+ * threaded replies, so the plugin declares
+ * `reactions/editMessages/deleteMessages/typing/threads: true`. `editMessages:true`
+ * auto-routes the channel to the edit-in-place activity strategy. `buttons` is
+ * `"adaptivecard"` — the channel advertises an Adaptive Card button surface. The
+ * send-reaction port methods (`reactToMessage`/`removeReaction`) are permanently
+ * omitted: Teams exposes no bot-reaction send API, so `reactions:true` is an
+ * INBOUND capability.
+ *
+ * @module
+ */
+import type { ChannelPluginPort, MediaResolverPort } from "@comis/core";
+import { type Result } from "@comis/shared";
+import { type MsTeamsAdapterDeps } from "./msteams-adapter.js";
+/**
+ * Structural interface for the auth-capable SSRF-guarded fetcher (avoids a
+ * circular dep on the package that owns the HTTP transport). It is the auth
+ * superset of the plain `fetch(url)` seam: `opts` carries the Authorization
+ * header value and the host allowlist the header may ride.
+ */
+interface SsrfFetcher {
+    fetch(url: string, opts?: {
+        authHeader?: string;
+        authAllowHosts?: readonly string[];
+    }): Promise<Result<{
+        buffer: Buffer;
+        mimeType: string;
+        sizeBytes: number;
+    }, Error>>;
+}
+/** Minimal logger interface for the media resolver. */
+interface ResolverLogger {
+    debug(obj: Record<string, unknown>, msg: string): void;
+    warn(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * The Teams plugin handle. Widens ChannelPluginPort with `createResolver`, which
+ * builds the Teams media resolver closing over the adapter's Connector-token
+ * getter (mirrors TelegramPluginHandle).
+ */
+export interface MsTeamsPluginHandle extends ChannelPluginPort {
+    /**
+     * Create the Teams media resolver. The injected fetcher is the auth-capable
+     * SSRF-guarded fetcher the media pipeline already uses; `mediaAuthAllowHosts`
+     * is the config passthrough (the resolver applies a built-in default when it
+     * is empty).
+     */
+    createResolver(deps: {
+        ssrfFetcher: SsrfFetcher;
+        maxBytes: number;
+        logger: ResolverLogger;
+        mediaAuthAllowHosts: readonly string[];
+    }): MediaResolverPort;
+}
+/**
+ * Create a Microsoft Teams channel plugin wrapping the Teams adapter.
+ *
+ * activate() delegates to adapter.start() and deactivate() to adapter.stop(),
+ * while the plugin declares its honest capability matrix.
+ */
+export declare function createMsTeamsPlugin(deps: MsTeamsAdapterDeps): MsTeamsPluginHandle;
+export {};

package/node_modules/@comis/channels/dist/msteams/msteams-plugin.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams Channel Plugin: wraps the Teams adapter as a ChannelPluginPort
+ * with capability-parity metadata.
+ *
+ * The adapter implements inbound reactions, edit/delete, a typing keepalive and
+ * threaded replies, so the plugin declares
+ * `reactions/editMessages/deleteMessages/typing/threads: true`. `editMessages:true`
+ * auto-routes the channel to the edit-in-place activity strategy. `buttons` is
+ * `"adaptivecard"` — the channel advertises an Adaptive Card button surface. The
+ * send-reaction port methods (`reactToMessage`/`removeReaction`) are permanently
+ * omitted: Teams exposes no bot-reaction send API, so `reactions:true` is an
+ * INBOUND capability.
+ *
+ * @module
+ */
+import { ok } from "@comis/shared";
+import { createMsTeamsAdapter, } from "./msteams-adapter.js";
+import { createMsTeamsResolver } from "./msteams-resolver.js";
+/** Microsoft Teams platform capabilities — self-declared, matching the adapter. */
+const CAPABILITIES = {
+    features: {
+        // Inbound reactions only; the send-reaction methods stay omitted.
+        reactions: true,
+        // Bot Framework updateActivity — auto-routes to the edit-in-place strategy.
+        editMessages: true,
+        // Bot Framework deleteActivity.
+        deleteMessages: true,
+        fetchHistory: false,
+        // Base64-inline image send via sendAttachment; inbound media resolves through
+        // the msteams-file resolver createResolver builds.
+        attachments: true,
+        // A {type:"typing"} keepalive over the injected timer.
+        typing: true,
+        // Channel/group thread root via replyToId.
+        threads: true,
+        // Advertises an Adaptive Card button surface.
+        buttons: "adaptivecard",
+    },
+    limits: {
+        maxMessageChars: 28000,
+    },
+    replyToMetaKey: "teamsActivityId",
+};
+/**
+ * Create a Microsoft Teams channel plugin wrapping the Teams adapter.
+ *
+ * activate() delegates to adapter.start() and deactivate() to adapter.stop(),
+ * while the plugin declares its honest capability matrix.
+ */
+export function createMsTeamsPlugin(deps) {
+    const adapter = createMsTeamsAdapter(deps);
+    return {
+        id: "channel-msteams",
+        name: "Microsoft Teams Channel Plugin",
+        version: "1.0.0",
+        channelType: "msteams",
+        capabilities: CAPABILITIES,
+        adapter,
+        register(_api) {
+            return ok(undefined);
+        },
+        async activate() {
+            return adapter.start();
+        },
+        async deactivate() {
+            return adapter.stop();
+        },
+        createResolver({ ssrfFetcher, maxBytes, logger, mediaAuthAllowHosts }) {
+            return createMsTeamsResolver({
+                // Close over the adapter's cached Connector-token getter; the resolver
+                // mints the Bearer once and the fetcher decides per-hop whether to attach it.
+                getToken: () => adapter.getConnectorToken(),
+                ssrfFetcher,
+                maxBytes,
+                logger,
+                mediaAuthAllowHosts,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Microsoft Teams proactive-send helpers — pure logic over injected ports.
+ *
+ * A reply rides the inbound activity's own serviceUrl; a PROACTIVE send (cron,
+ * heartbeat, an unsolicited notice) has no inbound activity, so it recovers the
+ * routing tuple from the conversation store keyed by the conversation id. This
+ * file holds the pure pieces of that path — no SQLite, no transport — so the
+ * adapter stays the controller:
+ *
+ *  - {@link rebuildConversationReference} maps a stored reference to the send
+ *    inputs, RE-VALIDATING the stored serviceUrl through the caller's host guard
+ *    on every send. A stored serviceUrl is untrusted at read (it could have been
+ *    tampered), so a poisoned value is rejected before a token is ever minted —
+ *    the freshly minted Connector bearer token can never be sent to a foreign
+ *    host.
+ *
+ * @module
+ */
+import type { ConversationReference } from "@comis/core";
+import { type Result } from "@comis/shared";
+/** The routing inputs a proactive Connector send needs, recovered from the store. */
+export interface ProactiveSendTarget {
+    /** The per-conversation service base URL to POST to (host-re-validated). */
+    serviceUrl: string;
+    /** The AAD tenant the conversation belongs to. */
+    tenantId: string;
+    /** The channel/group thread root to thread under, when present. */
+    threadId?: string;
+}
+/**
+ * Map a stored {@link ConversationReference} to a {@link ProactiveSendTarget},
+ * re-validating the stored serviceUrl through the injected host guard. Returns
+ * `err` when the stored serviceUrl fails the guard — the interim stored-reference
+ * defense that keeps the bearer token from reaching a poisoned host.
+ *
+ * `isSafeServiceUrl` is injected (rather than imported) so this helper stays pure
+ * and the adapter remains the single owner of the host allowlist.
+ */
+export declare function rebuildConversationReference(stored: ConversationReference, isSafeServiceUrl: (serviceUrl: string) => boolean): Result<ProactiveSendTarget, Error>;

package/node_modules/@comis/channels/dist/msteams/msteams-proactive.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams proactive-send helpers — pure logic over injected ports.
+ *
+ * A reply rides the inbound activity's own serviceUrl; a PROACTIVE send (cron,
+ * heartbeat, an unsolicited notice) has no inbound activity, so it recovers the
+ * routing tuple from the conversation store keyed by the conversation id. This
+ * file holds the pure pieces of that path — no SQLite, no transport — so the
+ * adapter stays the controller:
+ *
+ *  - {@link rebuildConversationReference} maps a stored reference to the send
+ *    inputs, RE-VALIDATING the stored serviceUrl through the caller's host guard
+ *    on every send. A stored serviceUrl is untrusted at read (it could have been
+ *    tampered), so a poisoned value is rejected before a token is ever minted —
+ *    the freshly minted Connector bearer token can never be sent to a foreign
+ *    host.
+ *
+ * @module
+ */
+import { err, ok } from "@comis/shared";
+/**
+ * Map a stored {@link ConversationReference} to a {@link ProactiveSendTarget},
+ * re-validating the stored serviceUrl through the injected host guard. Returns
+ * `err` when the stored serviceUrl fails the guard — the interim stored-reference
+ * defense that keeps the bearer token from reaching a poisoned host.
+ *
+ * `isSafeServiceUrl` is injected (rather than imported) so this helper stays pure
+ * and the adapter remains the single owner of the host allowlist.
+ */
+export function rebuildConversationReference(stored, isSafeServiceUrl) {
+    if (!isSafeServiceUrl(stored.serviceUrl)) {
+        return err(new Error("stored service url failed the path-safety check"));
+    }
+    return ok({
+        serviceUrl: stored.serviceUrl,
+        tenantId: stored.tenantId,
+        threadId: stored.threadId,
+    });
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Microsoft Teams reaction binder — the pure inbound-reaction mapper.
+ *
+ * Teams has no live SDK reaction callback: reactions arrive as
+ * `messageReaction` activities pushed through the same webhook the message path
+ * uses. So this file carries only the PURE transform — a `messageReaction`
+ * activity to a {@link NormalizedReaction} — while the fan-out loop over the
+ * registered handlers lives in the adapter alongside the message fan-out.
+ *
+ * The reactor id is UNTRUSTED inbound data; no trust is assigned here. The
+ * reaction is minted through {@link parseReaction} so its `z.strictObject`
+ * rejects any smuggled field (e.g. a trust/authority claim) before it leaves
+ * the adapter.
+ *
+ * @module
+ */
+import type { NormalizedReaction } from "@comis/core";
+import type { TeamsActivity } from "./message-mapper.js";
+/**
+ * A Bot Framework `messageReaction` activity — the shared {@link TeamsActivity}
+ * shape plus the reaction list that only reaction activities carry. Additive:
+ * the message path never reads `reactionsAdded`.
+ */
+export interface TeamsReactionActivity extends TeamsActivity {
+    reactionsAdded?: ReadonlyArray<{
+        type: string;
+    }>;
+}
+/**
+ * Map a Bot Framework `messageReaction` activity to a NormalizedReaction.
+ *
+ * Returns null for a non-reaction activity, an empty/unknown reaction type, or
+ * an activity missing a reaction target or reactor — the adapter skips those.
+ *
+ * @param activity - A Bot Framework inbound activity
+ * @returns A validated NormalizedReaction, or null to skip
+ */
+export declare function mapMsTeamsReaction(activity: TeamsReactionActivity): NormalizedReaction | null;