mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-07 11:01:24 +00:00
Matrix-js: sync with main plugin-loading standards
This commit is contained in:
Gustavo Madeira Santana
563
extensions/matrix-js/src/onboarding.ts
Normal file
563
extensions/matrix-js/src/onboarding.ts
Normal file
@@ -0,0 +1,563 @@
|
||||
import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
|
||||
import type { DmPolicy } from "openclaw/plugin-sdk/matrix-js";
|
||||
import {
|
||||
addWildcardAllowFrom,
|
||||
formatDocsLink,
|
||||
mergeAllowFromEntries,
|
||||
normalizeAccountId,
|
||||
promptAccountId,
|
||||
promptChannelAccessConfig,
|
||||
type RuntimeEnv,
|
||||
type ChannelOnboardingAdapter,
|
||||
type ChannelOnboardingDmPolicy,
|
||||
type WizardPrompter,
|
||||
} from "openclaw/plugin-sdk/matrix-js";
|
||||
import { migrateMatrixLegacyCredentialsToDefaultAccount } from "./config-migration.js";
|
||||
import { listMatrixDirectoryGroupsLive } from "./directory-live.js";
|
||||
import {
|
||||
listMatrixAccountIds,
|
||||
resolveDefaultMatrixAccountId,
|
||||
resolveMatrixAccount,
|
||||
resolveMatrixAccountConfig,
|
||||
} from "./matrix/accounts.js";
|
||||
import {
|
||||
getMatrixScopedEnvVarNames,
|
||||
hasReadyMatrixEnvAuth,
|
||||
resolveScopedMatrixEnvConfig,
|
||||
} from "./matrix/client.js";
|
||||
import { updateMatrixAccountConfig } from "./matrix/config-update.js";
|
||||
import { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./matrix/deps.js";
|
||||
import { resolveMatrixTargets } from "./resolve-targets.js";
|
||||
import type { CoreConfig } from "./types.js";
|
||||
|
||||
const channel = "matrix-js" as const;
|
||||
|
||||
function setMatrixDmPolicy(cfg: CoreConfig, policy: DmPolicy) {
|
||||
const allowFrom =
|
||||
policy === "open"
|
||||
? addWildcardAllowFrom(cfg.channels?.["matrix-js"]?.dm?.allowFrom)
|
||||
: undefined;
|
||||
return {
|
||||
...cfg,
|
||||
channels: {
|
||||
...cfg.channels,
|
||||
"matrix-js": {
|
||||
...cfg.channels?.["matrix-js"],
|
||||
dm: {
|
||||
...cfg.channels?.["matrix-js"]?.dm,
|
||||
policy,
|
||||
...(allowFrom ? { allowFrom } : {}),
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async function noteMatrixAuthHelp(prompter: WizardPrompter): Promise<void> {
|
||||
await prompter.note(
|
||||
[
|
||||
"Matrix requires a homeserver URL.",
|
||||
"Use an access token (recommended) or password login to an existing account.",
|
||||
"With access token: user ID is fetched automatically.",
|
||||
"Env vars supported: MATRIX_HOMESERVER, MATRIX_USER_ID, MATRIX_ACCESS_TOKEN, MATRIX_PASSWORD, MATRIX_DEVICE_ID, MATRIX_DEVICE_NAME.",
|
||||
"Per-account env vars: MATRIX_<ACCOUNT_ID>_HOMESERVER, MATRIX_<ACCOUNT_ID>_USER_ID, MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN, MATRIX_<ACCOUNT_ID>_PASSWORD, MATRIX_<ACCOUNT_ID>_DEVICE_ID, MATRIX_<ACCOUNT_ID>_DEVICE_NAME.",
|
||||
`Docs: ${formatDocsLink("/channels/matrix-js", "channels/matrix-js")}`,
|
||||
].join("\n"),
|
||||
"Matrix setup",
|
||||
);
|
||||
}
|
||||
|
||||
async function promptMatrixAllowFrom(params: {
|
||||
cfg: CoreConfig;
|
||||
prompter: WizardPrompter;
|
||||
accountId?: string;
|
||||
}): Promise<CoreConfig> {
|
||||
const { cfg, prompter } = params;
|
||||
const existingAllowFrom = cfg.channels?.["matrix-js"]?.dm?.allowFrom ?? [];
|
||||
const account = resolveMatrixAccount({ cfg });
|
||||
const canResolve = Boolean(account.configured);
|
||||
|
||||
const parseInput = (raw: string) =>
|
||||
raw
|
||||
.split(/[\n,;]+/g)
|
||||
.map((entry) => entry.trim())
|
||||
.filter(Boolean);
|
||||
|
||||
const isFullUserId = (value: string) => value.startsWith("@") && value.includes(":");
|
||||
|
||||
while (true) {
|
||||
const entry = await prompter.text({
|
||||
message: "Matrix allowFrom (full @user:server; display name only if unique)",
|
||||
placeholder: "@user:server",
|
||||
initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
|
||||
validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
|
||||
});
|
||||
const parts = parseInput(String(entry));
|
||||
const resolvedIds: string[] = [];
|
||||
const pending: string[] = [];
|
||||
const unresolved: string[] = [];
|
||||
const unresolvedNotes: string[] = [];
|
||||
|
||||
for (const part of parts) {
|
||||
if (isFullUserId(part)) {
|
||||
resolvedIds.push(part);
|
||||
continue;
|
||||
}
|
||||
if (!canResolve) {
|
||||
unresolved.push(part);
|
||||
continue;
|
||||
}
|
||||
pending.push(part);
|
||||
}
|
||||
|
||||
if (pending.length > 0) {
|
||||
const results = await resolveMatrixTargets({
|
||||
cfg,
|
||||
inputs: pending,
|
||||
kind: "user",
|
||||
}).catch(() => []);
|
||||
for (const result of results) {
|
||||
if (result?.resolved && result.id) {
|
||||
resolvedIds.push(result.id);
|
||||
continue;
|
||||
}
|
||||
if (result?.input) {
|
||||
unresolved.push(result.input);
|
||||
if (result.note) {
|
||||
unresolvedNotes.push(`${result.input}: ${result.note}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (unresolved.length > 0) {
|
||||
const details = unresolvedNotes.length > 0 ? unresolvedNotes : unresolved;
|
||||
await prompter.note(
|
||||
`Could not resolve:\n${details.join("\n")}\nUse full @user:server IDs.`,
|
||||
"Matrix allowlist",
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
const unique = mergeAllowFromEntries(existingAllowFrom, resolvedIds);
|
||||
return {
|
||||
...cfg,
|
||||
channels: {
|
||||
...cfg.channels,
|
||||
"matrix-js": {
|
||||
...cfg.channels?.["matrix-js"],
|
||||
enabled: true,
|
||||
dm: {
|
||||
...cfg.channels?.["matrix-js"]?.dm,
|
||||
policy: "allowlist",
|
||||
allowFrom: unique,
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
function setMatrixGroupPolicy(cfg: CoreConfig, groupPolicy: "open" | "allowlist" | "disabled") {
|
||||
return {
|
||||
...cfg,
|
||||
channels: {
|
||||
...cfg.channels,
|
||||
"matrix-js": {
|
||||
...cfg.channels?.["matrix-js"],
|
||||
enabled: true,
|
||||
groupPolicy,
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function setMatrixGroupRooms(cfg: CoreConfig, roomKeys: string[]) {
|
||||
const groups = Object.fromEntries(roomKeys.map((key) => [key, { allow: true }]));
|
||||
return {
|
||||
...cfg,
|
||||
channels: {
|
||||
...cfg.channels,
|
||||
"matrix-js": {
|
||||
...cfg.channels?.["matrix-js"],
|
||||
enabled: true,
|
||||
groups,
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const dmPolicy: ChannelOnboardingDmPolicy = {
|
||||
label: "Matrix",
|
||||
channel,
|
||||
policyKey: "channels.matrix-js.dm.policy",
|
||||
allowFromKey: "channels.matrix-js.dm.allowFrom",
|
||||
getCurrent: (cfg) => (cfg as CoreConfig).channels?.["matrix-js"]?.dm?.policy ?? "pairing",
|
||||
setPolicy: (cfg, policy) => setMatrixDmPolicy(cfg as CoreConfig, policy),
|
||||
promptAllowFrom: promptMatrixAllowFrom,
|
||||
};
|
||||
|
||||
type MatrixConfigureIntent = "update" | "add-account";
|
||||
|
||||
async function runMatrixConfigure(params: {
|
||||
cfg: CoreConfig;
|
||||
runtime: RuntimeEnv;
|
||||
prompter: WizardPrompter;
|
||||
forceAllowFrom: boolean;
|
||||
accountOverrides?: Partial<Record<string, string>>;
|
||||
shouldPromptAccountIds?: boolean;
|
||||
intent: MatrixConfigureIntent;
|
||||
}): Promise<{ cfg: CoreConfig; accountId: string }> {
|
||||
let next = migrateMatrixLegacyCredentialsToDefaultAccount(params.cfg);
|
||||
await ensureMatrixSdkInstalled({
|
||||
runtime: params.runtime,
|
||||
confirm: async (message) =>
|
||||
await params.prompter.confirm({
|
||||
message,
|
||||
initialValue: true,
|
||||
}),
|
||||
});
|
||||
const defaultAccountId = resolveDefaultMatrixAccountId(next);
|
||||
let accountId = defaultAccountId || DEFAULT_ACCOUNT_ID;
|
||||
if (params.intent === "add-account") {
|
||||
const enteredName = String(
|
||||
await params.prompter.text({
|
||||
message: "Matrix account name",
|
||||
validate: (value) => (value?.trim() ? undefined : "Required"),
|
||||
}),
|
||||
).trim();
|
||||
accountId = normalizeAccountId(enteredName);
|
||||
if (enteredName !== accountId) {
|
||||
await params.prompter.note(`Account id will be "${accountId}".`, "Matrix account");
|
||||
}
|
||||
next = updateMatrixAccountConfig(next, accountId, { name: enteredName, enabled: true });
|
||||
} else {
|
||||
const override = params.accountOverrides?.[channel]?.trim();
|
||||
if (override) {
|
||||
accountId = normalizeAccountId(override);
|
||||
} else if (params.shouldPromptAccountIds) {
|
||||
accountId = await promptAccountId({
|
||||
cfg: next,
|
||||
prompter: params.prompter,
|
||||
label: "Matrix-js",
|
||||
currentId: accountId,
|
||||
listAccountIds: (inputCfg) => listMatrixAccountIds(inputCfg as CoreConfig),
|
||||
defaultAccountId,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
const existing = resolveMatrixAccountConfig({ cfg: next, accountId });
|
||||
const account = resolveMatrixAccount({ cfg: next, accountId });
|
||||
if (!account.configured) {
|
||||
await noteMatrixAuthHelp(params.prompter);
|
||||
}
|
||||
|
||||
const scopedEnv = resolveScopedMatrixEnvConfig(accountId, process.env);
|
||||
const defaultScopedEnv = resolveScopedMatrixEnvConfig(DEFAULT_ACCOUNT_ID, process.env);
|
||||
const globalEnv = {
|
||||
homeserver: process.env.MATRIX_HOMESERVER?.trim() ?? "",
|
||||
userId: process.env.MATRIX_USER_ID?.trim() ?? "",
|
||||
accessToken: process.env.MATRIX_ACCESS_TOKEN?.trim() || undefined,
|
||||
password: process.env.MATRIX_PASSWORD?.trim() || undefined,
|
||||
};
|
||||
const scopedReady = hasReadyMatrixEnvAuth(scopedEnv);
|
||||
const defaultScopedReady = hasReadyMatrixEnvAuth(defaultScopedEnv);
|
||||
const globalReady = hasReadyMatrixEnvAuth(globalEnv);
|
||||
const envReady =
|
||||
scopedReady || (accountId === DEFAULT_ACCOUNT_ID && (defaultScopedReady || globalReady));
|
||||
const envHomeserver =
|
||||
scopedEnv.homeserver ||
|
||||
(accountId === DEFAULT_ACCOUNT_ID
|
||||
? defaultScopedEnv.homeserver || globalEnv.homeserver
|
||||
: undefined);
|
||||
const envUserId =
|
||||
scopedEnv.userId ||
|
||||
(accountId === DEFAULT_ACCOUNT_ID ? defaultScopedEnv.userId || globalEnv.userId : undefined);
|
||||
|
||||
if (
|
||||
envReady &&
|
||||
!existing.homeserver &&
|
||||
!existing.userId &&
|
||||
!existing.accessToken &&
|
||||
!existing.password
|
||||
) {
|
||||
const scopedEnvNames = getMatrixScopedEnvVarNames(accountId);
|
||||
const envSourceHint =
|
||||
accountId === DEFAULT_ACCOUNT_ID
|
||||
? "MATRIX_* or MATRIX_DEFAULT_*"
|
||||
: `${scopedEnvNames.homeserver} (+ auth vars)`;
|
||||
const useEnv = await params.prompter.confirm({
|
||||
message: `Matrix env vars detected (${envSourceHint}). Use env values?`,
|
||||
initialValue: true,
|
||||
});
|
||||
if (useEnv) {
|
||||
next = updateMatrixAccountConfig(next, accountId, { enabled: true });
|
||||
if (params.forceAllowFrom) {
|
||||
next = await promptMatrixAllowFrom({ cfg: next, prompter: params.prompter });
|
||||
}
|
||||
return { cfg: next, accountId };
|
||||
}
|
||||
}
|
||||
|
||||
const homeserver = String(
|
||||
await params.prompter.text({
|
||||
message: "Matrix homeserver URL",
|
||||
initialValue: existing.homeserver ?? envHomeserver,
|
||||
validate: (value) => {
|
||||
const raw = String(value ?? "").trim();
|
||||
if (!raw) {
|
||||
return "Required";
|
||||
}
|
||||
if (!/^https?:\/\//i.test(raw)) {
|
||||
return "Use a full URL (https://...)";
|
||||
}
|
||||
return undefined;
|
||||
},
|
||||
}),
|
||||
).trim();
|
||||
|
||||
let accessToken = existing.accessToken ?? "";
|
||||
let password = existing.password ?? "";
|
||||
let userId = existing.userId ?? "";
|
||||
|
||||
if (accessToken || password) {
|
||||
const keep = await params.prompter.confirm({
|
||||
message: "Matrix credentials already configured. Keep them?",
|
||||
initialValue: true,
|
||||
});
|
||||
if (!keep) {
|
||||
accessToken = "";
|
||||
password = "";
|
||||
userId = "";
|
||||
}
|
||||
}
|
||||
|
||||
if (!accessToken && !password) {
|
||||
const authMode = await params.prompter.select({
|
||||
message: "Matrix auth method",
|
||||
options: [
|
||||
{ value: "token", label: "Access token (user ID fetched automatically)" },
|
||||
{ value: "password", label: "Password (requires user ID)" },
|
||||
],
|
||||
});
|
||||
|
||||
if (authMode === "token") {
|
||||
accessToken = String(
|
||||
await params.prompter.text({
|
||||
message: "Matrix access token",
|
||||
validate: (value) => (value?.trim() ? undefined : "Required"),
|
||||
}),
|
||||
).trim();
|
||||
userId = "";
|
||||
} else {
|
||||
userId = String(
|
||||
await params.prompter.text({
|
||||
message: "Matrix user ID",
|
||||
initialValue: existing.userId ?? envUserId,
|
||||
validate: (value) => {
|
||||
const raw = String(value ?? "").trim();
|
||||
if (!raw) {
|
||||
return "Required";
|
||||
}
|
||||
if (!raw.startsWith("@")) {
|
||||
return "Matrix user IDs should start with @";
|
||||
}
|
||||
if (!raw.includes(":")) {
|
||||
return "Matrix user IDs should include a server (:server)";
|
||||
}
|
||||
return undefined;
|
||||
},
|
||||
}),
|
||||
).trim();
|
||||
password = String(
|
||||
await params.prompter.text({
|
||||
message: "Matrix password",
|
||||
validate: (value) => (value?.trim() ? undefined : "Required"),
|
||||
}),
|
||||
).trim();
|
||||
}
|
||||
}
|
||||
|
||||
const deviceName = String(
|
||||
await params.prompter.text({
|
||||
message: "Matrix device name (optional)",
|
||||
initialValue: existing.deviceName ?? "OpenClaw Gateway",
|
||||
}),
|
||||
).trim();
|
||||
|
||||
const enableEncryption = await params.prompter.confirm({
|
||||
message: "Enable end-to-end encryption (E2EE)?",
|
||||
initialValue: existing.encryption ?? false,
|
||||
});
|
||||
|
||||
next = updateMatrixAccountConfig(next, accountId, {
|
||||
enabled: true,
|
||||
homeserver,
|
||||
userId: userId || null,
|
||||
accessToken: accessToken || null,
|
||||
password: password || null,
|
||||
deviceName: deviceName || null,
|
||||
encryption: enableEncryption,
|
||||
});
|
||||
|
||||
if (params.forceAllowFrom) {
|
||||
next = await promptMatrixAllowFrom({ cfg: next, prompter: params.prompter });
|
||||
}
|
||||
|
||||
const existingGroups =
|
||||
next.channels?.["matrix-js"]?.groups ?? next.channels?.["matrix-js"]?.rooms;
|
||||
const accessConfig = await promptChannelAccessConfig({
|
||||
prompter: params.prompter,
|
||||
label: "Matrix rooms",
|
||||
currentPolicy: next.channels?.["matrix-js"]?.groupPolicy ?? "allowlist",
|
||||
currentEntries: Object.keys(existingGroups ?? {}),
|
||||
placeholder: "!roomId:server, #alias:server, Project Room",
|
||||
updatePrompt: Boolean(existingGroups),
|
||||
});
|
||||
if (accessConfig) {
|
||||
if (accessConfig.policy !== "allowlist") {
|
||||
next = setMatrixGroupPolicy(next, accessConfig.policy);
|
||||
} else {
|
||||
let roomKeys = accessConfig.entries;
|
||||
if (accessConfig.entries.length > 0) {
|
||||
try {
|
||||
const resolvedIds: string[] = [];
|
||||
const unresolved: string[] = [];
|
||||
for (const entry of accessConfig.entries) {
|
||||
const trimmed = entry.trim();
|
||||
if (!trimmed) {
|
||||
continue;
|
||||
}
|
||||
const cleaned = trimmed.replace(/^(room|channel):/i, "").trim();
|
||||
if (cleaned.startsWith("!") && cleaned.includes(":")) {
|
||||
resolvedIds.push(cleaned);
|
||||
continue;
|
||||
}
|
||||
const matches = await listMatrixDirectoryGroupsLive({
|
||||
cfg: next,
|
||||
query: trimmed,
|
||||
limit: 10,
|
||||
});
|
||||
const exact = matches.find(
|
||||
(match) => (match.name ?? "").toLowerCase() === trimmed.toLowerCase(),
|
||||
);
|
||||
const best = exact ?? matches[0];
|
||||
if (best?.id) {
|
||||
resolvedIds.push(best.id);
|
||||
} else {
|
||||
unresolved.push(entry);
|
||||
}
|
||||
}
|
||||
roomKeys = [...resolvedIds, ...unresolved.map((entry) => entry.trim()).filter(Boolean)];
|
||||
if (resolvedIds.length > 0 || unresolved.length > 0) {
|
||||
await params.prompter.note(
|
||||
[
|
||||
resolvedIds.length > 0 ? `Resolved: ${resolvedIds.join(", ")}` : undefined,
|
||||
unresolved.length > 0
|
||||
? `Unresolved (kept as typed): ${unresolved.join(", ")}`
|
||||
: undefined,
|
||||
]
|
||||
.filter(Boolean)
|
||||
.join("\n"),
|
||||
"Matrix rooms",
|
||||
);
|
||||
}
|
||||
} catch (err) {
|
||||
await params.prompter.note(
|
||||
`Room lookup failed; keeping entries as typed. ${String(err)}`,
|
||||
"Matrix rooms",
|
||||
);
|
||||
}
|
||||
}
|
||||
next = setMatrixGroupPolicy(next, "allowlist");
|
||||
next = setMatrixGroupRooms(next, roomKeys);
|
||||
}
|
||||
}
|
||||
|
||||
return { cfg: next, accountId };
|
||||
}
|
||||
|
||||
export const matrixOnboardingAdapter: ChannelOnboardingAdapter = {
|
||||
channel,
|
||||
getStatus: async ({ cfg }) => {
|
||||
const account = resolveMatrixAccount({ cfg: cfg as CoreConfig });
|
||||
const configured = account.configured;
|
||||
const sdkReady = isMatrixSdkAvailable();
|
||||
return {
|
||||
channel,
|
||||
configured,
|
||||
statusLines: [
|
||||
`Matrix: ${configured ? "configured" : "needs homeserver + access token or password"}`,
|
||||
],
|
||||
selectionHint: !sdkReady ? "install matrix-js-sdk" : configured ? "configured" : "needs auth",
|
||||
};
|
||||
},
|
||||
configure: async ({
|
||||
cfg,
|
||||
runtime,
|
||||
prompter,
|
||||
forceAllowFrom,
|
||||
accountOverrides,
|
||||
shouldPromptAccountIds,
|
||||
}) =>
|
||||
await runMatrixConfigure({
|
||||
cfg: cfg as CoreConfig,
|
||||
runtime,
|
||||
prompter,
|
||||
forceAllowFrom,
|
||||
accountOverrides,
|
||||
shouldPromptAccountIds,
|
||||
intent: "update",
|
||||
}),
|
||||
configureInteractive: async ({
|
||||
cfg,
|
||||
runtime,
|
||||
prompter,
|
||||
forceAllowFrom,
|
||||
accountOverrides,
|
||||
shouldPromptAccountIds,
|
||||
configured,
|
||||
}) => {
|
||||
if (!configured) {
|
||||
return await runMatrixConfigure({
|
||||
cfg: cfg as CoreConfig,
|
||||
runtime,
|
||||
prompter,
|
||||
forceAllowFrom,
|
||||
accountOverrides,
|
||||
shouldPromptAccountIds,
|
||||
intent: "update",
|
||||
});
|
||||
}
|
||||
const action = await prompter.select({
|
||||
message: "Matrix-js already configured. What do you want to do?",
|
||||
options: [
|
||||
{ value: "update", label: "Modify settings" },
|
||||
{ value: "add-account", label: "Add account" },
|
||||
{ value: "skip", label: "Skip (leave as-is)" },
|
||||
],
|
||||
initialValue: "update",
|
||||
});
|
||||
if (action === "skip") {
|
||||
return "skip";
|
||||
}
|
||||
return await runMatrixConfigure({
|
||||
cfg: cfg as CoreConfig,
|
||||
runtime,
|
||||
prompter,
|
||||
forceAllowFrom,
|
||||
accountOverrides,
|
||||
shouldPromptAccountIds,
|
||||
intent: action === "add-account" ? "add-account" : "update",
|
||||
});
|
||||
},
|
||||
dmPolicy,
|
||||
disable: (cfg) => ({
|
||||
...(cfg as CoreConfig),
|
||||
channels: {
|
||||
...(cfg as CoreConfig).channels,
|
||||
"matrix-js": { ...(cfg as CoreConfig).channels?.["matrix-js"], enabled: false },
|
||||
},
|
||||
}),
|
||||
};
|
||||
Reference in New Issue
Block a user