fix(matrix): allow configured homeserver login

[gabrielrinaldi]

Summary

• Problem: Matrix password login uses fetchWithSsrFGuard without a homeserver-scoped SSRF policy, so configured homeservers that resolve to private/internal IPs can be blocked during fresh login.
• Why it matters: new Matrix accounts on operator-controlled internal homeservers cannot complete first-time login, which prevents channel startup and downstream E2EE verification.
• What changed: derive allowedHostnames from the configured Matrix homeserver URL and attach that policy only to the matrix.login guarded fetch; add a unit test covering the new login policy wiring.
• What did NOT change (scope boundary): no broad private-network bypass, no config schema changes, and no changes to other Matrix requests.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

User-visible / Behavior Changes

• Matrix accounts configured with channels.matrix.userId + channels.matrix.password can now log in against a configured homeserver whose DNS resolves to a private/internal IP, as long as the request stays on that configured hostname.

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:
  • The request is still guarded by SSRF policy. This change only allowlists the explicitly configured homeserver hostname for the Matrix login call instead of allowing private networks broadly.

Repro + Verification

Environment

• OS: NixOS (dev workstation)
• Runtime/container: Node + pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): Matrix
• Relevant config (redacted): channels.matrix.homeserver=https://matrix.cloud-city.dev, channels.matrix.userId=@clio:cloud-city.dev, password-based login

Steps

1. Configure Matrix with homeserver, userId, and password, using a homeserver hostname that resolves to a private/internal IP from the OpenClaw host.
2. Start OpenClaw without a cached Matrix access token for that account.
3. Observe the password login flow hitting /_matrix/client/v3/login through the guarded fetch.

Expected

• Password login is allowed for the explicitly configured homeserver hostname, and the account can obtain/store its access token.

Actual

• Before this patch, the login request can fail with Blocked: resolves to private/internal/special-use IP address.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Added a unit test that asserts resolveMatrixAuth passes policy: { allowedHostnames: [configured-hostname] } to the guarded Matrix login fetch.
  • Ran pnpm vitest run extensions/matrix/src/matrix/client.test.ts and confirmed it passes.
  • Ran pnpm build successfully in a shell with pnpm available on PATH.
• Edge cases checked:
  • Helper fails closed for empty/invalid homeserver values and does not introduce a broad private-network bypass.
  • Only the matrix.login request path is changed.
• What you did not verify:
  • I did not run a live end-to-end Matrix login against a private homeserver from this checkout.
  • Full repo-wide pnpm check and pnpm test are currently blocked by unrelated upstream issues in this checkout (for example a formatting issue in src/cli/daemon-cli/lifecycle.test.ts and unrelated test failures outside Matrix).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert commit 280d086b6
• Files/config to restore: extensions/matrix/src/matrix/client/config.ts, extensions/matrix/src/matrix/client.test.ts
• Known bad symptoms reviewers should watch for: unexpected Matrix login failures on malformed homeserver URLs or any regression in guarded login fetch behavior.

Risks and Mitigations

• Risk: Login now treats the configured Matrix homeserver hostname as an explicitly trusted endpoint.
  • Mitigation: the allowlist is exact-host only, scoped to the configured homeserver, and only applied to the password login request.

AI-assisted: yes. Testing: targeted unit test + local build.

[greptile-apps]

Greptile Summary

This PR fixes a Matrix password login failure on operator-controlled homeservers whose DNS resolves to private/internal IP addresses. Previously, the fetchWithSsrFGuard call for matrix.login had no SSRF policy override, so any homeserver hostname that resolves to a private IP would be blocked.

Key changes:

• Adds buildMatrixHomeserverPolicy(homeserver) in extensions/matrix/src/matrix/client/config.ts, which parses the configured homeserver URL and returns { allowedHostnames: [hostname] }, or undefined for empty/invalid/non-HTTP inputs (fail-closed).
• Passes the derived policy as the policy field to the existing fetchWithSsrFGuard login call, scoped exclusively to the matrix.login request path.
• Adds a targeted unit test confirming the policy wiring.

The implementation is well-scoped: the allowlist is exact-hostname-only, applied only to the login fetch, and the SSRF guard (including redirect SSRF checks) remains fully active for any other hostname. The hostname extraction uses standard URL API behavior, ensuring consistency with SSRF enforcement. No other request paths are affected.

Confidence Score: 5/5

• This PR is safe to merge. The change is narrow, fail-closed, and introduces no broad private-network bypass.
• The fix is tightly scoped to a single fetch call. The helper is fail-closed for all invalid inputs (empty strings, invalid URLs, non-HTTP protocols). The policy is applied only to the matrix.login request, leaving the SSRF guard active for all other hostnames. A targeted unit test covers the policy wiring. No other request paths or security boundaries are affected.
• No files require special attention.

_{Last reviewed commit: 280d086}

[gumadeiras]

OpenClaw now uses a new Matrix plugin built on the official matrix-js-sdk. The older Matrix implementation is no longer supported.

Closing this as potentially fixed in the new plugin. If this still reproduces after migrating, please open a new issue/PR against the new Matrix plugin and link back here.

Migration/docs:
https://docs.openclaw.ai/channels/matrix
https://docs.openclaw.ai/install/migrating-matrix