Npm-valid package scopes with dots/underscores cannot map to ClawHub publishers

[Patrick-Erichsen]

Summary

ClawHub currently requires scoped package names to match the selected/owning publisher handle exactly. That is good for preventing ambiguous ownership, but we found four existing plugin packages whose package.json.name scopes are valid on npm and already published on npm, while the same scopes are invalid as ClawHub publisher handles.

ClawHub publisher handles currently allow only lowercase letters, numbers, and hyphens. npm scopes can include dots and underscores, so these packages cannot be repaired by creating matching ClawHub orgs under the current handle rules.

Affected packages

cc for visibility: @bitrouter @gelin-cloud @thepluglabai @juan-xin-cai

Package	Current ClawHub owner	Source repo	npm status	Problem
@bitrouter.ai/openclaw-plugin	@takasaki404	bitrouter/bitrouter-openclaw	exists on npm as 0.1.1	scope contains .
@glin_1/miniabc	@gelin-cloud	gelincloud/miniabc-plugin	exists on npm as 2.0.14	scope contains _
@pluglab_thinkly/thinkly-openclaw-plugin	@thepluglabai	pluglabai/thinkly-openclaw-plugin	exists on npm as 0.1.3	scope contains _
@souls_market/openclaw-plugin	@juan-xin-cai	Gyliiiiii/souls-market	exists on npm as 0.0.7	scope contains _

Why this matters

For scoped plugin packages, ClawHub now enforces:

package.json name scope == ClawHub publisher handle

That means a package named:

"name": "@bitrouter.ai/openclaw-plugin"

must publish under ClawHub publisher:

bitrouter.ai

But ClawHub rejects bitrouter.ai as a publisher handle. Creating a similar handle like bitrouter-ai does not help, because --owner bitrouter-ai still mismatches the package scope @bitrouter.ai.

Current behavior

These packages remain in a mismatched ownership state after the org-repair migration because ClawHub cannot create matching publishers for their npm scopes.

Expected publish failure shape:

Cannot publish @bitrouter.ai/openclaw-plugin: package.json name is scoped to "@bitrouter.ai", but ClawHub publisher handles may only use lowercase letters, numbers, and hyphens.

or, if using a similar owner:

Package scope "@bitrouter.ai" must match selected owner "@bitrouter-ai".

Options

1. Allow npm-compatible scope characters in ClawHub publisher handles

   • At minimum, consider . and _.
   • This aligns ClawHub publisher handles with package scopes already valid on npm.

2. Keep ClawHub handles slug-safe and require package renames

   • Example: @bitrouter.ai/openclaw-plugin -> @bitrouter-ai/openclaw-plugin.
   • This is cleaner for ClawHub URLs, but it forces users to change existing npm package identity.

3. Add explicit scope-to-publisher aliases

   • Example: npm scope bitrouter.ai maps to ClawHub publisher bitrouter-ai.
   • This avoids broad handle changes but adds a new ownership indirection that publish, install, UI, and transfer flows must understand.

Recommendation

We should decide intentionally whether ClawHub publisher handles are meant to be URL slugs or npm-scope-compatible identities.

Given ClawHub now uses package scope as the ownership source of truth for scoped packages, my lean is to support npm-compatible scope characters for publisher handles, or introduce a first-class alias mechanism. Otherwise these packages cannot be made publishable without asking maintainers to rename already-published npm packages.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 18, 2026, 4:19 PM ET / 20:19 UTC.

Summary
Keep open for explicit maintainer handling: current main and the v0.22.0 release contain the npm-compatible publisher-handle implementation, but this collaborator-authored issue concerns package-scope publish authority and should not be auto-closed by cleanup.

Reproducibility: no. Current-main source and regression tests accept dotted and underscored publisher handles, and v0.22.0 source contains the same handle pattern, so the original invalid-handle failure no longer reproduces by source inspection.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
No new repair PR is needed because main and v0.22.0 contain the implementation; the remaining action is maintainer closure and security/product acceptance.

Security
Needs attention: No patch is under review, but publisher handle and package-scope matching is a publish-authority boundary that should remain a maintainer security decision.

Review details

Best possible solution:

Keep the npm-compatible handle implementation and have a maintainer explicitly close or accept the remaining ownership-boundary state after any production package verification.

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

No. Current-main source and regression tests accept dotted and underscored publisher handles, and v0.22.0 source contains the same handle pattern, so the original invalid-handle failure no longer reproduces by source inspection.

Is this the best way to solve the issue?

Yes. The merged implementation is the narrowest maintainable solution because it aligns publisher handles with npm scope identity while preserving exact scope-owner matching; aliases would be a separate security/product decision.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Automatic cleanup should not close this collaborator-authored ownership-boundary issue without explicit maintainer acceptance.
• Maintainers may still want to confirm the four affected production packages have been repaired or intentionally handled before closing this issue.

Codex review notes: model internal, reasoning high; reviewed against 22d3cd133cb6; fix evidence: release v0.22.0, commit dfac8d83ceb5.

Label changes

Label justifications:

• P2: The issue affects a bounded but real plugin publishing and ownership repair path for existing scoped packages.
• impact:security: Package-scope-to-publisher matching controls package ownership and publish authorization boundaries.

Evidence reviewed

Security concerns:

• [medium] Keep alias decisions explicit — packages/schema/src/packages.ts:14
  Current main preserves exact package-scope-to-publisher matching; any future alias mechanism would add ownership indirection and should receive explicit maintainer security review.
  Confidence: 0.84

What I checked:

• Repository policy read: Read the full target AGENTS.md and applied its ClawHub/Convex/security-sensitive ownership guidance to this read-only review. (AGENTS.md:1, 22d3cd133cb6)
• Issue is collaborator-authored: Live GitHub GraphQL reports the issue authorAssociation as COLLABORATOR, which the cleanup policy treats as requiring explicit maintainer judgment rather than auto-close.
• Current validator accepts dots and underscores: Current main allows publisher handles with lowercase letters, numbers, hyphens, dots, and underscores, bounded by alphanumeric characters. (convex/lib/publishers.ts:10, 22d3cd133cb6)
• Org creation uses shared validation: Self-serve org publisher creation normalizes and validates requested handles through validateHandle before uniqueness checks and insertion. (convex/publishers.ts:128, 22d3cd133cb6)
• Publish guidance preserves exact scoped owners: The missing-publisher message now treats npm-compatible dotted or underscored scopes as valid handles and suggests creating the exact matching publisher. (convex/packages.ts:325, 22d3cd133cb6)
• Regression coverage accepts npm-compatible handles: Publisher tests create org publishers for dotted and underscored handles, and package publish tests suggest creating a dotted publisher for a scoped package. (convex/publishers.test.ts:4136, 22d3cd133cb6)

Likely related people:

• Patrick-Erichsen: Authored the merged npm-compatible handle fix, the self-serve publisher creation feature, and the scoped plugin ownership enforcement path around this behavior. (role: fix author and recent publisher/package area contributor; confidence: high; commits: dfac8d83ceb5, 0b888a2d1371, 1aab139775a4; files: convex/lib/publishers.ts, convex/publishers.ts, convex/packages.ts)
• Peter Steinberger: Authored earlier legacy publisher-handle-to-org migration work and adjacent publisher identity changes that shaped the ownership repair area. (role: publisher ownership migration feature-history contributor; confidence: medium; commits: 22287558b9d3, 6c15a481d042, e6a3bdf4e36e; files: convex/publishers.ts, convex/users.ts, docs/http-api.md)

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.

[github-actions]

This issue has been automatically marked as stale due to inactivity.
Please add updated ClawHub details or it will be closed.