Release room-scoped Matrix bot plugins and room configuration

This commit is contained in:
Matrix Bot Project committed 2026-11-20 23:23:04 +08:00
commit 86c7e4359c
76 files changed
+13539

No files matched your search

+43
View File
@@ -0,0 +1,43 @@
# cross-sign 一次性工具
给 bot 设备做 **cross-signing(交叉签名)**,让它在 Element 设备列表里显示为
「已验证」(绿盾),并触发你的其它设备自动向 bot 分享房间密钥(从而能解部分旧消息)。
## 为什么需要它
bot 主程序用的是 `matrix-bot-sdk`,其底层加密内核
(`@matrix-org/[email protected]`)**不支持设备验证 / cross-signing**,
所以你在 Element 里点「验证」会一直卡在「等待对方接受」。
本工具改用官方 **`matrix-js-sdk`**(支持完整验证)临时登录一次,从你的
Secret Storage(4S)取出 cross-signing 私钥,直接给目标设备签名 —— 等价于
Element 里 SAS 对暗号成功后的那一步。签完立即登出并删除这个临时设备。
**bot 运行时完全不受影响。**
## 前提
你的 Matrix 账号必须**已设置过 cross-signing + 安全密钥(Security Key)或安全短语**
(Element → 设置 → 安全与隐私 → 加密)。
## 用法
```bash
cd scripts/cross-sign
npm install # 首次需要
node ./cross-sign.mjs
```
然后按提示**交互式粘贴**即可(无需任何环境变量 / 配置文件):
1. 输入账号域名或 API 地址
2. 输入完整的 Matrix 用户 ID,例如 `@bot:example.org`
3. 账号密码 —— **粘贴时不回显**
4. 安全密钥(base58,如 `EsTc ...`)—— 不回显;直接回车则改填安全短语
5. 输入要签名的设备 ID。留空后还需输入 `ALL` 才会签名所有未验证设备。
跑一次即可,之后无需再跑(除非 bot 重新登录产生了新设备)。
## 注意
- 密码、恢复密钥/短语只在本机脚本内使用,不会上传任何第三方;输入时不回显。
- 过程中会**短暂**出现一个名为 `cross-sign-temp (可删)` 的临时设备,脚本结束会自动删除。
+238
View File
@@ -0,0 +1,238 @@
/**
* 一次性交互脚本:用你的「恢复密钥 / 安全短语」给 bot 设备做 cross-signing。
*
* 背景:bot 跑的 matrix-bot-sdk(底层 crypto 0.4.0)不支持设备验证,
* 所以在 Element 里点「验证」会一直卡住。本脚本用官方 matrix-js-sdk
* 临时登录一次,从你的 Secret Storage(4S)取出 cross-signing 私钥,
* 直接给目标设备签名(等价于 Element 里 SAS 验证成功后的那一步),
* 签完立刻登出这个临时设备。bot 运行时完全不动。
*
* 用法:node ./cross-sign.mjs 然后按提示粘贴即可。
*/
import { createClient, AutoDiscovery } from 'matrix-js-sdk';
import { decodeRecoveryKey } from 'matrix-js-sdk/lib/crypto-api/recovery-key.js';
import { pbkdf2 } from 'node:crypto';
import { promisify } from 'node:util';
import { createInterface } from 'node:readline';
import { stdin, stdout } from 'node:process';
const pbkdf2Async = promisify(pbkdf2);
function fail(msg) {
console.error(`❌ ${msg}`);
process.exit(1);
}
/** 普通提问;支持默认值(直接回车采用) */
function ask(question, def) {
const rl = createInterface({ input: stdin, output: stdout });
const suffix = def ? ` [${def}]` : '';
return new Promise((resolve) => {
rl.question(`${question}${suffix}: `, (ans) => {
rl.close();
resolve((ans.trim() || def || '').trim());
});
});
}
/** 隐藏输入(粘贴时不回显),用于密码 / 恢复密钥 */
function askSecret(question) {
return new Promise((resolve) => {
// 先把提示语打印出来(可见),再静音后续按键回显
stdout.write(`${question}: `);
const rl = createInterface({ input: stdin, output: stdout });
rl._writeToOutput = function (str) {
// 仅放行换行,其余按键不回显
if (str.includes('\n')) rl.output.write('\n');
};
rl.question('', (ans) => {
rl.close();
resolve(ans.trim());
});
});
}
let RECOVERY_KEY = '';
let SECURITY_PHRASE = '';
let PASSWORD = '';
let TARGET_DEVICE_ID = '';
async function main() {
console.log('=== bot 设备 cross-signing 工具 ===\n');
const homeserverInput = await ask('账号域名或 API 地址');
if (!homeserverInput) fail('必须输入账号域名或 API 地址。');
const userId = await ask('账号 user id');
if (!userId) fail('必须输入账号 ID。');
PASSWORD = await askSecret('账号密码(粘贴,不回显)');
if (!PASSWORD) fail('必须输入密码。');
console.log(
'\n签名需要你的「安全密钥」或「安全短语」二选一。安全密钥优先,直接回车切到安全短语。',
);
RECOVERY_KEY = await askSecret('安全密钥(base58,如 EsTc...;不回显)');
if (RECOVERY_KEY) {
try {
decodeRecoveryKey(RECOVERY_KEY.replace(/\s+/g, ''));
} catch {
fail('安全密钥格式不对(应是 EsTx... 的 base58,4 字符一组共 12 组)。');
}
} else {
SECURITY_PHRASE = await askSecret('安全短语(不回显)');
if (!SECURITY_PHRASE) fail('安全密钥和安全短语必须至少提供一个。');
}
TARGET_DEVICE_ID = await ask('要签名的设备 ID');
if (!TARGET_DEVICE_ID && await ask('签名所有未验证设备?输入 ALL 确认') !== 'ALL') {
fail('未选择签名目标。');
}
// 1) 解析真实 API 地址(支持裸域名 well-known 发现)
const baseUrl = await resolveBaseUrl(homeserverInput);
console.log(`\n🔗 homeserver API: ${baseUrl}`);
// 2) 临时登录(产生一个临时设备,结束后登出删除)
const loginClient = createClient({ baseUrl });
console.log('🔑 临时登录中...');
const login = await loginClient.login('m.login.password', {
identifier: { type: 'm.id.user', user: userId },
password: PASSWORD,
initial_device_display_name: 'cross-sign-temp (可删)',
});
const accessToken = login.access_token;
const deviceId = login.device_id;
const realUserId = login.user_id;
console.log(`✅ 临时设备已登录: ${deviceId}`);
// 3) 构建带 crypto 的 client,提供 secret storage 取钥回调
const client = createClient({
baseUrl,
accessToken,
userId: realUserId,
deviceId,
cryptoCallbacks: { getSecretStorageKey },
});
let signedOk = false;
try {
await client.initRustCrypto({ useIndexedDB: false });
const crypto = client.getCrypto();
if (!crypto) fail('crypto 初始化失败。');
console.log('🔄 启动同步(拉取设备列表 / secret storage)...');
await client.startClient({ initialSyncLimit: 1 });
await waitForSync(client);
// 4) 从 4S 导入 cross-signing 私钥(不重置已有密钥)
console.log('📥 从 Secret Storage 导入 cross-signing 私钥...');
await crypto.bootstrapCrossSigning({
authUploadDeviceSigningKeys: async (makeRequest) => {
await makeRequest({
type: 'm.login.password',
identifier: { type: 'm.id.user', user: realUserId },
password: PASSWORD,
});
},
});
if (!(await crypto.isCrossSigningReady())) {
fail(
'cross-signing 未就绪——恢复密钥/短语可能不对,或账号未设置过 cross-signing。',
);
}
console.log('✅ cross-signing 私钥就绪。');
// 5) 确定要签名的设备
const targets = await resolveTargets(crypto, realUserId, deviceId);
if (targets.length === 0) {
console.log('ℹ️ 没有需要签名的设备(可能都已验证)。');
}
for (const dev of targets) {
console.log(`✍️ 签名设备 ${dev} ...`);
await crypto.crossSignDevice(dev);
const st = await crypto.getDeviceVerificationStatus(realUserId, dev);
console.log(` → crossSigningVerified=${st?.crossSigningVerified ?? '?'}`);
}
signedOk = true;
} finally {
// 6) 清理:登出临时设备(删除它),停止 client
try {
client.stopClient();
} catch {}
try {
console.log('🧹 登出并删除临时设备...');
await client.logout(true);
console.log('✅ 临时设备已删除。');
} catch (e) {
console.warn('⚠️ 登出临时设备失败(可手动在 Element 删除):', e?.message);
}
}
if (signedOk) {
console.log('\n🎉 完成!刷新 Element 设备列表即可看到目标设备已验证(绿盾)。');
}
process.exit(signedOk ? 0 : 1);
}
/** secret storage 取钥回调:用恢复密钥或安全短语派生 4S 密钥 */
async function getSecretStorageKey({ keys }) {
const keyId = Object.keys(keys)[0];
const info = keys[keyId];
let privateKey;
if (RECOVERY_KEY) {
privateKey = decodeRecoveryKey(RECOVERY_KEY.replace(/\s+/g, ''));
} else {
const pp = info?.passphrase;
if (!pp?.salt || !pp?.iterations) {
fail('该账号的 4S 没有 passphrase 信息,请改用安全密钥。');
}
privateKey = new Uint8Array(
await pbkdf2Async(SECURITY_PHRASE, pp.salt, pp.iterations, 32, 'sha512'),
);
}
return [keyId, privateKey];
}
/** 决定签名目标:指定了 TARGET_DEVICE_ID 就只签它;否则签名所有未交叉验证的自有设备(除临时设备) */
async function resolveTargets(crypto, userId, tempDeviceId) {
if (TARGET_DEVICE_ID) return [TARGET_DEVICE_ID];
const map = await crypto.getUserDeviceInfo([userId], true);
const devices = map.get(userId);
const out = [];
if (!devices) return out;
for (const devId of devices.keys()) {
if (devId === tempDeviceId) continue;
const st = await crypto.getDeviceVerificationStatus(userId, devId);
if (!st?.crossSigningVerified) out.push(devId);
}
return out;
}
/** well-known 发现:裸域名 → 真实 API 地址 */
async function resolveBaseUrl(input) {
if (/^https?:\/\//.test(input)) return input.replace(/\/$/, '');
const res = await AutoDiscovery.findClientConfig(input);
const url = res?.['m.homeserver']?.base_url;
if (!url) fail(`无法从 ${input} 发现 homeserver,请直接填完整 API 地址。`);
return url.replace(/\/$/, '');
}
/** 等待首次同步完成 */
function waitForSync(client) {
return new Promise((resolve, reject) => {
const to = setTimeout(() => reject(new Error('同步超时(60s)')), 60_000);
client.once('sync', function handler(state) {
if (state === 'PREPARED') {
clearTimeout(to);
resolve();
} else if (state === 'ERROR') {
clearTimeout(to);
reject(new Error('同步出错'));
}
});
});
}
main().catch((e) => {
console.error('💥 出错:', e);
process.exit(1);
});
+216
View File
@@ -0,0 +1,216 @@
{
"name": "cross-sign-tool",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "cross-sign-tool",
"version": "1.0.0",
"dependencies": {
"matrix-js-sdk": "^34.0.0"
}
},
"node_modules/@babel/runtime": {
"version": "7.29.7",
"resolved": "https://registry.npmmirror.com/@babel/runtime/-/runtime-7.29.7.tgz",
"integrity": "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==",
"license": "MIT",
"engines": {
"node": ">=6.9.0"
}
},
"node_modules/@matrix-org/matrix-sdk-crypto-wasm": {
"version": "9.1.0",
"resolved": "https://registry.npmmirror.com/@matrix-org/matrix-sdk-crypto-wasm/-/matrix-sdk-crypto-wasm-9.1.0.tgz",
"integrity": "sha512-CtPoNcoRW6ehwxpRQAksG3tR+NJ7k4DV02nMFYTDwQtie1V4R8OTY77BjEIs97NOblhtS26jU8m1lWsOBEz0Og==",
"license": "Apache-2.0",
"engines": {
"node": ">= 10"
}
},
"node_modules/@matrix-org/olm": {
"version": "3.2.15",
"resolved": "https://registry.npmmirror.com/@matrix-org/olm/-/olm-3.2.15.tgz",
"integrity": "sha512-S7lOrndAK9/8qOtaTq/WhttJC/o4GAzdfK0MUPpo8ApzsJEC0QjtwrkC3KBXdFP1cD1MXi/mlKR7aaoVMKgs6Q==",
"license": "Apache-2.0"
},
"node_modules/@types/events": {
"version": "3.0.3",
"resolved": "https://registry.npmmirror.com/@types/events/-/events-3.0.3.tgz",
"integrity": "sha512-trOc4AAUThEz9hapPtSd7wf5tiQKvTtu5b371UxXdTuqzIh0ArcRspRP0i0Viu+LXstIQ1z96t1nsPxT9ol01g==",
"license": "MIT"
},
"node_modules/@types/retry": {
"version": "0.12.0",
"resolved": "https://registry.npmmirror.com/@types/retry/-/retry-0.12.0.tgz",
"integrity": "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==",
"license": "MIT"
},
"node_modules/another-json": {
"version": "0.2.0",
"resolved": "https://registry.npmmirror.com/another-json/-/another-json-0.2.0.tgz",
"integrity": "sha512-/Ndrl68UQLhnCdsAzEXLMFuOR546o2qbYRqCglaNHbjXrwG1ayTcdwr3zkSGOGtGXDyR5X9nCFfnyG2AFJIsqg==",
"license": "Apache-2.0"
},
"node_modules/base-x": {
"version": "5.0.1",
"resolved": "https://registry.npmmirror.com/base-x/-/base-x-5.0.1.tgz",
"integrity": "sha512-M7uio8Zt++eg3jPj+rHMfCC+IuygQHHCOU+IYsVtik6FWjuYpVt/+MRKcgsAMHh8mMFAwnB+Bs+mTrFiXjMzKg==",
"license": "MIT"
},
"node_modules/bs58": {
"version": "6.0.0",
"resolved": "https://registry.npmmirror.com/bs58/-/bs58-6.0.0.tgz",
"integrity": "sha512-PD0wEnEYg6ijszw/u8s+iI3H17cTymlrwkKhDhPZq+Sokl3AU4htyBFTjAeNAlCCmg0f53g6ih3jATyCKftTfw==",
"license": "MIT",
"dependencies": {
"base-x": "^5.0.0"
}
},
"node_modules/content-type": {
"version": "1.0.5",
"resolved": "https://registry.npmmirror.com/content-type/-/content-type-1.0.5.tgz",
"integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==",
"license": "MIT",
"engines": {
"node": ">= 0.6"
}
},
"node_modules/events": {
"version": "3.3.0",
"resolved": "https://registry.npmmirror.com/events/-/events-3.3.0.tgz",
"integrity": "sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==",
"license": "MIT",
"engines": {
"node": ">=0.8.x"
}
},
"node_modules/jwt-decode": {
"version": "4.0.0",
"resolved": "https://registry.npmmirror.com/jwt-decode/-/jwt-decode-4.0.0.tgz",
"integrity": "sha512-+KJGIyHgkGuIq3IEBNftfhW/LfWhXUIY6OmyVWjliu5KH1y0fw7VQ8YndE2O4qZdMSd9SqbnC8GOcZEy0Om7sA==",
"license": "MIT",
"engines": {
"node": ">=18"
}
},
"node_modules/loglevel": {
"version": "1.9.2",
"resolved": "https://registry.npmmirror.com/loglevel/-/loglevel-1.9.2.tgz",
"integrity": "sha512-HgMmCqIJSAKqo68l0rS2AanEWfkxaZ5wNiEFb5ggm08lDs9Xl2KxBlX3PTcaD2chBM1gXAYf491/M2Rv8Jwayg==",
"license": "MIT",
"engines": {
"node": ">= 0.6.0"
},
"funding": {
"type": "tidelift",
"url": "https://tidelift.com/funding/github/npm/loglevel"
}
},
"node_modules/matrix-events-sdk": {
"version": "0.0.1",
"resolved": "https://registry.npmmirror.com/matrix-events-sdk/-/matrix-events-sdk-0.0.1.tgz",
"integrity": "sha512-1QEOsXO+bhyCroIe2/A5OwaxHvBm7EsSQ46DEDn8RBIfQwN5HWBpFvyWWR4QY0KHPPnnJdI99wgRiAl7Ad5qaA==",
"license": "Apache-2.0"
},
"node_modules/matrix-js-sdk": {
"version": "34.13.0",
"resolved": "https://registry.npmmirror.com/matrix-js-sdk/-/matrix-js-sdk-34.13.0.tgz",
"integrity": "sha512-AAU8ZdCawca+7ucQfdcC3LA85OtCTV7QeqcjvKt/ZZhU3xL9VoawuoRQ+4R6H8KZnqyJmT4j7bdeC0jG4qcqLg==",
"license": "Apache-2.0",
"dependencies": {
"@babel/runtime": "^7.12.5",
"@matrix-org/matrix-sdk-crypto-wasm": "^9.0.0",
"@matrix-org/olm": "3.2.15",
"another-json": "^0.2.0",
"bs58": "^6.0.0",
"content-type": "^1.0.4",
"jwt-decode": "^4.0.0",
"loglevel": "^1.7.1",
"matrix-events-sdk": "0.0.1",
"matrix-widget-api": "^1.10.0",
"oidc-client-ts": "^3.0.1",
"p-retry": "4",
"sdp-transform": "^2.14.1",
"unhomoglyph": "^1.0.6",
"uuid": "11"
},
"engines": {
"node": ">=20.0.0"
}
},
"node_modules/matrix-widget-api": {
"version": "1.17.0",
"resolved": "https://registry.npmmirror.com/matrix-widget-api/-/matrix-widget-api-1.17.0.tgz",
"integrity": "sha512-5FHoo3iEP3Bdlv5jsYPWOqj+pGdFQNLWnJLiB0V7Ygne7bb+Gsj3ibyFyHWC6BVw+Z+tSW4ljHpO17I9TwStwQ==",
"license": "Apache-2.0",
"dependencies": {
"@types/events": "^3.0.0",
"events": "^3.2.0"
}
},
"node_modules/oidc-client-ts": {
"version": "3.5.0",
"resolved": "https://registry.npmmirror.com/oidc-client-ts/-/oidc-client-ts-3.5.0.tgz",
"integrity": "sha512-l2q8l9CTCTOlbX+AnK4p3M+4CEpKpyQhle6blQkdFhm0IsBqsxm15bYaSa11G7pWdsYr6epdsRZxJpCyCRbT8A==",
"license": "Apache-2.0",
"dependencies": {
"jwt-decode": "^4.0.0"
},
"engines": {
"node": ">=18"
}
},
"node_modules/p-retry": {
"version": "4.6.2",
"resolved": "https://registry.npmmirror.com/p-retry/-/p-retry-4.6.2.tgz",
"integrity": "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==",
"license": "MIT",
"dependencies": {
"@types/retry": "0.12.0",
"retry": "^0.13.1"
},
"engines": {
"node": ">=8"
}
},
"node_modules/retry": {
"version": "0.13.1",
"resolved": "https://registry.npmmirror.com/retry/-/retry-0.13.1.tgz",
"integrity": "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==",
"license": "MIT",
"engines": {
"node": ">= 4"
}
},
"node_modules/sdp-transform": {
"version": "2.15.0",
"resolved": "https://registry.npmmirror.com/sdp-transform/-/sdp-transform-2.15.0.tgz",
"integrity": "sha512-KrOH82c/W+GYQ0LHqtr3caRpM3ITglq3ljGUIb8LTki7ByacJZ9z+piSGiwZDsRyhQbYBOBJgr2k6X4BZXi3Kw==",
"license": "MIT",
"bin": {
"sdp-verify": "checker.js"
}
},
"node_modules/unhomoglyph": {
"version": "1.0.6",
"resolved": "https://registry.npmmirror.com/unhomoglyph/-/unhomoglyph-1.0.6.tgz",
"integrity": "sha512-7uvcWI3hWshSADBu4JpnyYbTVc7YlhF5GDW/oPD5AxIxl34k4wXR3WDkPnzLxkN32LiTCTKMQLtKVZiwki3zGg==",
"license": "MIT"
},
"node_modules/uuid": {
"version": "11.1.1",
"resolved": "https://registry.npmmirror.com/uuid/-/uuid-11.1.1.tgz",
"integrity": "sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==",
"funding": [
"https://github.com/sponsors/broofa",
"https://github.com/sponsors/ctavan"
],
"license": "MIT",
"bin": {
"uuid": "dist/esm/bin/uuid"
}
}
}
}
+10
View File
@@ -0,0 +1,10 @@
{
"name": "cross-sign-tool",
"private": true,
"version": "1.0.0",
"type": "module",
"description": "一次性脚本:用恢复密钥给 bot 设备做 cross-signing(变已验证)。",
"dependencies": {
"matrix-js-sdk": "^34.0.0"
}
}