Skip to content

fix(matrix): validate CLI numeric option ranges#92483

Merged
vincentkoc merged 1 commit into
openclaw:mainfrom
rohitjavvadi:fix/matrix-cli-timeout-validation
Jun 13, 2026
Merged

fix(matrix): validate CLI numeric option ranges#92483
vincentkoc merged 1 commit into
openclaw:mainfrom
rohitjavvadi:fix/matrix-cli-timeout-validation

Conversation

@rohitjavvadi

@rohitjavvadi rohitjavvadi commented Jun 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Reject out-of-range Matrix CLI numeric options before Matrix setup or verification work starts.
  • matrix verify self --timeout-ms now requires a positive integer.
  • matrix account add --initial-sync-limit now rejects negative values while still allowing zero and positive integers.
  • Out of scope: changing Matrix verification behavior, account setup behavior, or docs for these already-documented flags.

Linked context

Fixes #92482

Related: none.

Was this requested by a maintainer or owner? No; this came from local bug reproduction and is linked to the issue above.

Real behavior proof (required for external PRs)

  • Behavior or issue addressed: invalid Matrix CLI numeric values were accepted past the CLI boundary.
  • Real environment tested: local OpenClaw source checkout on macOS with a temporary OPENCLAW_CONFIG_PATH and OPENCLAW_STATE_DIR. The Matrix CLI source registration was invoked through Commander so the proof exercised the changed CLI code without touching my real config.
  • Exact steps or command run after this patch: ran the Matrix CLI source registration with Commander against two invalid commands: matrix verify self --timeout-ms -1 and matrix account add ... --initial-sync-limit -1, using a temporary config with dummy Matrix values.
  • Evidence after fix: copied terminal output from that local run:
verify self:
Self-verification failed: --timeout-ms must be a positive integer
Next steps:
- Run openclaw matrix verify self again and accept the request in another verified Matrix client for this account.
- Then run openclaw matrix verify status --verbose to confirm Cross-signing verified: yes and Signed by owner: yes.
account add:
Account setup failed: --initial-sync-limit must be a non-negative integer
verify_exit=1
account_add_exit=1
  • Observed result after fix: both invalid values fail immediately with the intended CLI validation errors and exit non-zero. No Matrix network/client work is started.
  • What was not tested: a real Matrix homeserver verification flow, because the invalid input should fail before any network behavior.
  • Proof limitations or environment constraints: the source-checkout root launcher in this local tree currently hits an unrelated built-dist optional dependency issue, so the proof invokes the Matrix CLI source registration directly with Commander.
  • Before evidence: the new regression tests failed before the fix. --timeout-ms -1 reached the verification path and produced Cannot read properties of undefined (reading 'id'); --initial-sync-limit -1 did not fail at the CLI boundary.

Tests and validation

  • node scripts/run-vitest.mjs extensions/matrix/src/cli.test.ts -t "rejects non-positive Matrix self-verification timeout values|rejects negative Matrix initial sync limits"
  • node scripts/run-vitest.mjs extensions/matrix/src/cli.test.ts
  • ./node_modules/.bin/oxfmt extensions/matrix/src/cli.ts extensions/matrix/src/cli.test.ts --check
  • ./node_modules/.bin/tsc -p extensions/matrix/tsconfig.json --noEmit
  • pnpm lint:extensions
  • git diff --check

Regression coverage added for negative --timeout-ms and negative --initial-sync-limit.

pnpm check:changed was attempted, but local crabbox failed its basic --version/--help sanity checks before reaching code checks.

Risk checklist

Did user-visible behavior change? (Yes/No)

Yes. Invalid negative Matrix CLI values now fail earlier with clearer errors.

Did config, environment, or migration behavior change? (Yes/No)

No migration or persisted config shape change. Account setup now rejects an invalid explicit --initial-sync-limit -1 instead of letting downstream normalization treat it as absent.

Did security, auth, secrets, network, or tool execution behavior change? (Yes/No)

No. The real-behavior proof uses dummy local values only; no secrets are required.

What is the highest-risk area?

Rejecting a value that previously slipped through.

How is that risk mitigated?

The accepted ranges match the downstream behavior: verification timeout must be positive; initial sync limit allows zero and positive integers but not negatives. Focused regression tests cover both boundaries.

Current review state

Ready for review. Nothing is currently waiting on the author.

@openclaw-barnacle openclaw-barnacle Bot added channel: matrix Channel integration: matrix size: S triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 12, 2026
@clawsweeper

clawsweeper Bot commented Jun 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 12, 2026, 11:37 AM ET / 15:37 UTC.

Summary
The PR adds lower-bound validation for Matrix --timeout-ms and --initial-sync-limit CLI options, moves rejection ahead of runtime work, and adds focused regression tests.

PR surface: Source +19, Tests +42. Total +61 across 2 files.

Reproducibility: yes. at source level with high confidence: current main permits the negative values past integer parsing, and the PR supplies before-and-after command evidence for both paths.

Review metrics: none identified.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • none.

Next step before merge

  • Proceed with normal maintainer review and landing; the paired issue should remain open until this PR merges.

Security
Cleared: The diff changes only Matrix plugin-local parsing and tests, with no dependency, permissions, secrets, artifact-download, package-resolution, or supply-chain changes.

Review details

Best possible solution:

Land the plugin-local early validation so verification timeouts remain positive and initial sync limits remain non-negative without changing persisted Matrix configuration or normal command behavior.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level with high confidence: current main permits the negative values past integer parsing, and the PR supplies before-and-after command evidence for both paths.

Is this the best way to solve the issue?

Yes. Validating once at the owning Matrix CLI boundary before runtime, configuration, or network-related work is the narrowest maintainable fix and preserves each option's distinct accepted range.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 3643de4ba7b6.

Label changes

Label changes:

  • add P2: The PR fixes a real user-facing Matrix CLI validation defect with a limited two-option blast radius.
  • add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal output from the changed Commander registration showing both invalid commands fail with the intended errors, exit non-zero, and do not begin Matrix work.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix terminal output from the changed Commander registration showing both invalid commands fail with the intended errors, exit non-zero, and do not begin Matrix work.

Label justifications:

  • P2: The PR fixes a real user-facing Matrix CLI validation defect with a limited two-option blast radius.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix terminal output from the changed Commander registration showing both invalid commands fail with the intended errors, exit non-zero, and do not begin Matrix work.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal output from the changed Commander registration showing both invalid commands fail with the intended errors, exit non-zero, and do not begin Matrix work.
Evidence reviewed

PR surface:

Source +19, Tests +42. Total +61 across 2 files.

View PR surface stats
Area Files Added Removed Net
Source 1 26 7 +19
Tests 1 42 0 +42
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 2 68 7 +61

What I checked:

  • Current-main validation gap: Current main accepts signed integers for both options without checking their semantic lower bounds, allowing invalid values to reach account setup or self-verification. (extensions/matrix/src/cli.ts:235, 3643de4ba7b6)
  • Early account-option validation: The branch validates the initial sync limit before obtaining the Matrix runtime, reading configuration, invoking setup validation, or writing configuration. (extensions/matrix/src/cli.ts:303, 4e51ee9ad8df)
  • Early verification-option validation: The branch requires a positive timeout before resolving the Matrix account or invoking self-verification, matching the downstream elapsed-time polling contract. (extensions/matrix/src/cli.ts:1181, 4e51ee9ad8df)
  • Regression coverage: Tests assert both the user-facing validation errors and that downstream verification, setup validation, and config writes are not invoked for invalid values. (extensions/matrix/src/cli.test.ts:404, 4e51ee9ad8df)
  • Config contract: The existing Matrix configuration accepts numeric initial sync limits without defining a conflicting stricter minimum; the PR changes only explicit CLI input validation and not persisted schema shape. (extensions/matrix/src/config-schema.ts:119, 3643de4ba7b6)
  • History provenance: Git blame and symbol history tie the affected current-main CLI parser, account-add handling, and self-verification command to commit 777f740. (extensions/matrix/src/cli.ts:277, 777f7409d814)

Likely related people:

  • mushuiyu886: Git blame attributes the current Matrix CLI parser, account-add option handling, and self-verification command to their recent merged commit. (role: introduced behavior; confidence: high; commits: 777f7409d814; files: extensions/matrix/src/cli.ts, extensions/matrix/src/setup-config.ts, extensions/matrix/src/matrix/actions/verification.ts)
  • Gustavo Madeira Santana: Git history shows substantial prior work rebuilding the Matrix plugin surface that owns configuration, setup, and verification behavior. (role: feature owner; confidence: medium; commits: 94693f7ff036; files: extensions/matrix/src/cli.ts, extensions/matrix/src/setup-config.ts, extensions/matrix/src/matrix/actions/verification.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@openclaw-barnacle openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 12, 2026
@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal backlog priority with limited blast radius. labels Jun 12, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jun 13, 2026
Closed
@vincentkoc
vincentkoc force-pushed the fix/matrix-cli-timeout-validation branch from 4e51ee9 to d75f118 Compare June 13, 2026 23:12
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 13, 2026
vincentkoc
vincentkoc approved these changes Jun 13, 2026
View reviewed changes

@vincentkoc vincentkoc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified for maintainer merge.

Proof:

  • node scripts/run-vitest.mjs extensions/matrix/src/cli.test.ts --maxWorkers=1 passed.
  • Autoreview clean: no accepted/actionable findings.
  • Crabbox AWS cbx_5c32f138ab3a / swift-lobster, run run_6e133b8b82e7: OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 CI=1 corepack pnpm check:changed passed.
  • Exact PR head d75f118299029b0516311646276cd2d6582379c5: 129 success / 24 skipped / 1 neutral / 0 failures / 0 pending.

Review notes:

  • --initial-sync-limit now validates before setup validation/config writes.
  • --timeout-ms now validates before Matrix account-context resolution.
  • This is CLI numeric validation only; no SSRF, shell execution, credential, or network-policy surface changed.

@vincentkoc
vincentkoc merged commit 3429e33 into openclaw:main Jun 13, 2026
159 checks passed
@rohitjavvadi rohitjavvadi mentioned this pull request Jun 15, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vincentkoc vincentkoc vincentkoc approved these changes

Assignees

No one assigned

Labels

channel: matrix Channel integration: matrix P2 Normal backlog priority with limited blast radius. proof: supplied External PR includes structured after-fix real behavior proof. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: S status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Matrix CLI accepts out-of-range numeric options

2 participants

@rohitjavvadi @vincentkoc