mirror of https://github.com/vercel/chat.git synced 2026-09-14 18:32:29 +08:00

Files

T

Santiago Medina caa63253c5 feat(x): add XChat encrypted messaging support (#745 )

## summary

new `@chat-adapter/xchat` adapter for XChat, X's encrypted messaging.
write bot logic once and hold encrypted 1:1 and group conversations like
the other Chat SDK adapters — all crypto handled inside the adapter via
`@xdevplatform/chat-xdk` (wasm), all REST via the typed
`@xdevplatform/xdk` client.

## background: chat-xdk


[`@xdevplatform/chat-xdk`](https://www.npmjs.com/package/@xdevplatform/chat-xdk)
is the official XChat cryptography SDK — a Rust core compiled to
WebAssembly that implements the XChat encryption protocol. it handles
per-conversation symmetric keys and key exchange, message
encryption/decryption, event signing and signature verification, and
encrypted media (secretstream). the bot's private keys live in a
PIN-protected [Juicebox](https://juicebox.xyz) store (secret-shared
across independent realms), so no key material sits in env vars or on
disk — the adapter unlocks with a PIN at startup. this adapter is the
glue: chat-xdk produces and consumes the encrypted envelopes, the typed
`@xdevplatform/xdk` client moves them over the X API, and everything is
normalized to the Chat SDK's `Thread`/`Message` model.

what it supports:
- encrypted send/receive in DMs and groups (webhook push + polling),
signature verification on by default
- mention detection from structured mention entities, swipe-replies to
the bot, and a plain-text `@handle` fallback; group replies go out as
quoted replies with TTL propagated
- `openDM(userId)`: starts (or reuses) an encrypted 1:1 —
cached/history-recovered conversation key, else a full key exchange so
the bot can message first
- media both ways: inbound attachments with lazy download+decrypt,
outbound encrypted (secretstream) via the 3-step upload flow
- edit and delete of the bot's own messages: edits are encrypted events
targeting the original's sequence id; deletes are locally signed
delete-for-all actions recipients verify
- reactions in and out, typing keep-alive while handlers run,
configurable group welcome message
- read receipts sent per delivered inbound message (`sendReadReceipts`,
default on)
- cards by degradation: text + tappable entities, link buttons as
`label: url` lines, primary link as a URL preview attachment with
optional encrypted banner

key design decisions:
- mdast stays the canonical format; markdown passes through as raw text
(XChat clients render plain text — no markdown), with URLs and @mentions
made tappable via entity spans and tables degraded to ASCII code blocks
- thread ids are `xchat:{conversationId}` (groups `g…`, 1:1s the sorted
participant pair)
- the first edit of a fresh message is age-gated (`editSafetyDelayMs`,
default 5000ms): receiving clients park an edit whose original hasn't
arrived, leaving the message permanently invisible — the gate prevents
that race
- undecryptable or unverified events are dropped, never delivered as
empty messages
- no core changes: the adapter implements the standard `Adapter`
interface only

also includes the `chat/adapters` catalog entry, docs page (with OG
image), `adapters.json` registry entry, and `create-chat-sdk` scaffold
spec, modeled on the `x` adapter's registration.

<details><summary>usage</summary>

```bash
XCHAT_BOT_TOKEN=...    # OAuth2 user access token (identity resolved from GET /2/users/me)
XCHAT_PIN=...          # Juicebox PIN that unlocks the bot's keys
X_CONSUMER_SECRET=...  # optional: verifies webhook signatures
```

```typescript
import { Chat } from "chat";
import { createXchatAdapter } from "@chat-adapter/xchat";
import { createMemoryState } from "@chat-adapter/state-memory";

const bot = new Chat({
  userName: "mybot",
  adapters: { xchat: createXchatAdapter() }, // credentials from env
  state: createMemoryState(),
});

// DMs always
bot.onDirectMessage(async (thread, message) => {
  await thread.post(`You said: ${message.text}`);
});

// group chats when the bot is @mentioned
bot.onNewMention(async (thread, message) => {
  await thread.post("You rang?");
});

// wire the webhook (e.g. a Next.js route)
export async function POST(request: Request) {
  return bot.webhooks.xchat(request);
}
```

</details>

testing: 109 unit tests, including real-wasm-crypto round trips against
vendored fixture vectors (decrypt + signature verification, webhook
delivery, read receipts, edit age-gating, signed deletes). verified live
against production XChat: DMs, group mentions, media, reactions, edits,
deletes, openDM, cards.

note on the lockfile: `@xdevplatform/xdk@0.6.6` was published <48h ago,
so it was resolved with a one-shot `--config.minimumReleaseAge=0`
override; the locked integrity hash was verified against the npm
registry. the repo policy file is untouched.

---------

Co-authored-by: dancer <josh@afterima.ge>

2026-07-31 23:52:18 +01:00

fixtures/replay

[messenger] add messenger (meta) platform adapter to chat sdk (#461 )

2026-05-08 17:25:54 +10:00

src

feat(x): add XChat encrypted messaging support (#745 )

2026-07-31 23:52:18 +01:00

package.json

build(deps-dev): bump @hono/node-server from 2.0.2 to 2.0.10 (#733 )

2026-07-22 13:15:31 +10:00

README.md

test(integration-tests): add Emulate.dev-backed tests for the GitHub adapter (#479 )

2026-05-13 07:12:55 +10:00

tsconfig.json

replay-tests

2025-12-31 16:10:32 -08:00

vitest.config.ts

Upgrade vitest

2026-02-27 09:58:28 -08:00

README.md

Integration Tests

Integration tests for the Chat SDK that verify real-world webhook payloads are handled correctly.

Test Categories

Unit tests (slack.test.ts, teams.test.ts, gchat.test.ts) - Test adapter functionality with mock payloads
Replay tests (replay*.test.ts) - Replay actual production webhook recordings
Emulator tests (src/emulator/<adapter>/*.test.ts) - Drive the SDK against an in-process Emulate.dev server, one per supported adapter (@emulators/slack, @emulators/github). Assertions read the emulator's stateful store (messages, comments, reactions, installations) instead of mock call records. Each adapter is wired in via its apiUrl config. Inbound deliveries: the Slack flow re-signs event_callback payloads with x-slack-signature via a small in-test forwarder before handing them to chat.webhooks.slack(...), while the GitHub flow is a near-passthrough because the emulator's WebhookDispatcher already signs with X-Hub-Signature-256 exactly as the adapter expects. Helpers live in src/emulator/slack/utils.ts and src/emulator/github/utils.ts.

Replay Tests

Replay tests use recorded webhook payloads from production to verify the SDK handles real interactions correctly.

See fixtures/replay/README.md for:

How to record new fixtures
Fixture format documentation
SHA-based recording workflow
Platform-specific webhook formats

Running Tests

# Run all integration tests
pnpm --filter @chat-adapter/integration-tests test

# Run with watch mode
pnpm --filter @chat-adapter/integration-tests test:watch