integration.provider-messaging

@lssm-tech/integration.provider-messaging

Website: https://contractspec.io

Messaging provider implementations for ContractSpec.

Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the ./impls/* subpaths.

Included Providers

• SlackMessagingProvider
• GithubMessagingProvider
• MatrixMessagingProvider
• TelegramMessagingProvider
• MetaWhatsappMessagingProvider
• TwilioWhatsappMessagingProvider
• createDiscordBotEcosystemAdapter
• createTeamsGraphEcosystemAdapter
• createTeamsBotEcosystemAdapter

Compatibility

This package owns the messaging implementation slice split out of @lssm-tech/integration.providers-impls. The legacy package continues to re-export these subpaths for existing consumers.

CommunicationOS OAuth

The ./wave-a-oauth-providers subpath exposes official Gmail, Microsoft Mail, Microsoft Teams, Slack, and Meta WhatsApp OAuth provider ports. Gmail, Microsoft, and PKCE-enabled Slack use authorization-code PKCE. Meta uses its Login for Business configuration and confidential client because its Embedded Signup surface does not advertise PKCE. Every flow keeps one-time state, resolves a stable provider account identity, writes only the flat credential shape consumed by the worker directly to an injected SecretProvider, and returns an opaque scope-bound credential reference. Meta authorization reports oauth_authorized until Embedded Signup also binds a WABA and phone-number ID; it does not claim messaging capability early. Telegram remains bot-secret based and does not pretend to offer an OAuth flow.

createMicrosoftMailOAuthProvider requests delegated Mail.Read and Mail.Send, resolves the signed-in mailbox through Graph /me, and writes the access token, refresh token, returned scopes, expiry, and sender address only to the scoped credential vault. Its provider key is microsoft; Gmail retains the google key and remains the default when both are configured. The connection also advertises subscription capability so a qualified CommunicationOS lifecycle worker can request Graph subscription create or renewal through Runtime Node authority. The OAuth callback does not perform that provider effect directly.

refreshMicrosoftDelegatedCredential refreshes only inside a bounded expiry window, requires the original client and refresh-token material from that same credential, rejects scope narrowing, and rotates through a caller-supplied exact-reference callback. Provider error bodies and tokens never become receipts, journal content, or fallback evidence.

Discord

createDiscordBotEcosystemAdapter provides the managed outbound Discord bot transport. It pins REST API v10, authenticates with a bot token, checks the bot identity through /users/@me, sends to channel or thread snowflake IDs, and derives Discord's bounded nonce from the durable idempotency key with enforce_nonce enabled. Ambient mentions are disabled unless a future governed policy explicitly enables them.

Transport failures, 5xx responses, and malformed 2xx responses are classified as indeterminate and require reconciliation rather than automatic retry or fallback. Rate limits retain the provider retry delay. The adapter does not claim guild installation, Gateway ingestion, interaction callbacks, privileged intents, history sync, attachments, reactions, editing, deletion, or read receipts.

Inbound and multi-guild observation live in the dedicated @lssm-tech/integration.communication-channel-discord package. This package retains the outbound adapter and compatibility export only; consumers must not infer inbound support from the generic synthetic adapter profile.

The dependency validator recognizes exactly this messaging-to-Discord edge as an existing compatibility facade. It is not a provider foundation or a general channel exemption: the target must remain a provider-free leaf, with no internal dependencies outside @lssm-tech/lib.*. Missing targets, other providers/channels, runtime back-edges, and all integration cycles still fail qualification. New observation consumers should import the channel package directly.

Store the bot token behind an opaque scoped secret reference. Guild-installed apps still require an authorized Discord installation with the bot scope and least-privilege channel permissions before this adapter can send.

Microsoft Teams

createTeamsGraphEcosystemAdapter is the canonical outbound Microsoft Graph adapter for a user-authorized Teams connection. It accepts only a non-expired delegated credential containing User.Read and ChannelMessage.Send, sends a plain-text message to an explicit team and channel, and classifies network, server, and malformed-success outcomes as indeterminate until reconciliation. It never treats Teamwork.Migrate.All or a client-credentials token as ordinary messaging authority.

createTeamsOAuthProvider performs authorization-code PKCE against Microsoft identity, verifies the signed-in account through /me, and writes the access token, refresh token, exact returned scopes, and expiry directly to the scoped credential vault. The current managed worker refuses expired tokens; automatic refresh and live ambiguous-result reconciliation remain separate qualification gates.

Microsoft Graph channel send is an on-behalf-of-user route. Autonomous Teams app notifications require an installed Teams bot/app and persisted conversation reference. createTeamsBotEcosystemAdapter provides that distinct proactive transport: it acquires a Bot Connector service token, accepts only Microsoft Teams service URLs, requires evidence that the conversation reference was captured from an authorized installation, and sends a message activity to that conversation. Token failures occur before the message effect; transport, 5xx, and malformed-success outcomes after token acquisition remain indeterminate. Blocked or uninstalled bots are definitive failures and do not silently fall back.

When Microsoft returns a safe diagnostic correlation header on an ambiguous Graph or Bot Connector response, the typed provider error retains only an opaque teams:*request:* evidence ref. It never retains response bodies, authorization data, or arbitrary headers. A diagnostic ref improves custody and operator escalation, but does not itself prove acceptance or failure.

createTeamsBotInboundAdapter and createTeamsBotConnectorJwtVerifier provide the matching admission path. The verifier accepts only bearer JWTs signed by an endorsed Bot Connector key, pins the published issuer, audience, RS256 algorithm, Microsoft metadata and key endpoints, applies the documented lifetime tolerance, and requires the signed serviceUrl to equal the activity value. CommunicationOS additionally requires its scoped endpoint token before this provider authentication runs.

Authenticated activities durably record a tenant- and connection-scoped conversation reference with its authentication evidence. Signed installationUpdate/remove activities revoke that reference, and active resolution refuses revoked references. The managed delivery context strips caller-supplied Bot Connector addressing and rehydrates serviceUrl and evidence only from that active journal projection before adapter health or send. Single-tenant profiles also bind the activity tenant to the configured tenant. Live app installation, Runtime Node effect execution, and ambiguous-send reconciliation remain qualification gates. No adapter accepts a user Graph token as a bot credential or a Bot Framework app secret as delegated-user authority.

Slack

SlackMessagingProvider implements Slack message send/update/delete plus conversations, users, reactions, files, and search operations over the Slack Web API. It requires a bot token for standard Web API calls and can optionally use a user token for search endpoints that require user-scoped Slack permissions.

Import it from:

import { SlackMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-slack";

const slack = new SlackMessagingProvider({
	botToken: process.env.SLACK_BOT_TOKEN!,
	userToken: process.env.SLACK_USER_TOKEN,
	defaultChannelId: "C0123456789",
});

await slack.sendMessage({ text: "ContractSpec check passed" });
const search = await slack.searchMessages("ContractSpec", 10);

For inbound Slack Event API requests, verify signatures and normalize events through @lssm-tech/integration.runtime/channel/slack or the higher-level Slack webhook receiver in @lssm-tech/integration.runtime/webhooks/slack. Keep botToken, userToken, app tokens, and signing secrets in a SecretProvider or environment secret store; never commit real Slack credentials, raw webhook URLs, or signed payload logs.

GitHub

GithubMessagingProvider implements the messaging bridge for GitHub issue and pull request comments. Use recipientId in the owner/repo#number form, or configure defaultOwner and defaultRepo and pass the issue/PR number as threadId.

Import it from:

import { GithubMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-github";

const github = new GithubMessagingProvider({
	token: process.env.GITHUB_TOKEN!,
	defaultOwner: "lssm-tech",
	defaultRepo: "contractspec",
});

await github.sendMessage({
	threadId: "42",
	text: "ContractSpec automation result",
});

For repository, issue, pull request, merge, and code-search operations, use @lssm-tech/integration.provider-github. For inbound GitHub webhook requests, verify signatures and normalize channel events through @lssm-tech/integration.runtime/channel/github or the webhook receiver in @lssm-tech/integration.runtime/webhooks/github. Keep personal access tokens, GitHub App installation tokens, private keys, and webhook secrets in managed secrets; test fixtures should use redacted placeholders and mocked fetch responses only.

Matrice

MatrixMessagingProvider is a minimal matrix-js-sdk adapter for Matrix room sends and mocked room-event normalization. It expects an existing homeserver URL and access token; it does not provision homeservers, automate hosted signup, install bridges, guarantee production bridge operation, or replace direct Slack/Telegram/WhatsApp providers.

Import it from:

import { MatrixMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-matrix";

Personal device channels

The ./personal-device-bridge subpath models the owner's personal WhatsApp account and Android SMS inbox as personal-mode channels, separate from the official business adapters above. A binding carries its own consent, an explicit coverage start and read_only access by default. A device companion implements PersonalDeviceBridgePort; PersonalDeviceRegistry pairs it with a one-time code, tracks heartbeat/offline/revoked state and projects a per-capability matrix (unsupported, disabled, unqualified, qualified). SMS never implies RCS, and nothing is inferred from OAuth or business profiles.

No qualified device transport ships today: without one the channel reports unsupported and blocked, and the fixture transport is deliberately unqualified. catchUpPersonalDevice is read-only (cursor + sequence replay protection, missing media reported as missingEvidence, owner-sent messages as message.sent_by_owner). sendPersonalMessage requires a qualified, consented, read_write, online binding and the owner_personal audience; ambiguous sends stay uncertain. Business credential factories refuse personal credentials via isPersonalChannelCredential.