fix: harden v2 custom widgets and Workshop (#6480)
This commit is contained in:
1 parent
f77c47b94b
commit
400127b45c
138 files changed
+5134
-1977
No files matched your search
@@ -4,6 +4,9 @@ An external agent creates one widget at a time with the Homarr MCP server. The a
|
||||
|
||||
Homarr does not create widget packs or drafts for multiple widgets.
|
||||
|
||||
The MCP API key must belong to a Homarr administrator. Non-administrator keys do not list Custom Widget tools, prompts,
|
||||
or resources. The same administrator requirement applies to the matching HTTP authoring endpoints.
|
||||
|
||||
<a className="button button--primary" href="https://www.skills.sh/homarr-labs/homarr/homarr-custom-widget">
|
||||
View the Custom Widget Skill on skills.sh
|
||||
</a>
|
||||
@@ -67,7 +70,10 @@ These interfaces do not return an archive URL or archive hash.
|
||||
12. Update the saved definition if the final verification finds a problem.
|
||||
13. Repeat the procedure for the next widget.
|
||||
|
||||
Each source-configuration URL applies to one definition or preview and one source. The user confirms the server URL, network scope, and required credential fields directly in Homarr. The agent receives only request status and never receives plaintext credentials. Preview-scoped values expire with that preview; definition-scoped values persist.
|
||||
Each source-configuration URL applies to one definition or preview and one source. It is short-lived, single-use, and
|
||||
can only be opened and completed by an authenticated Homarr administrator. The administrator confirms the server URL,
|
||||
network scope, and required credential fields directly in Homarr. The agent receives only request status and never
|
||||
receives plaintext credentials. Preview-scoped values expire with that preview; definition-scoped values persist.
|
||||
|
||||
Agents can install existing widgets without regenerating them:
|
||||
|
||||
@@ -88,8 +94,11 @@ Homarr maintainers can run the same self-contained prompt that the workbench cop
|
||||
OPENROUTER_API_KEY=... pnpm --filter @homarr/custom-widgets test:ai
|
||||
```
|
||||
|
||||
The suite uses DeepSeek V4 Pro to author five complex widgets and DeepSeek V4 Flash to judge only widgets that pass Homarr's real parser and canonical schema. It saves every response, validated `widget.json`, `widget.jsx`, and detailed category scores under `packages/custom-widgets/.ai-evaluations/`.
|
||||
The suite uses DeepSeek V4 Pro to author Pokédex, Portainer, football, Jellyfin, and Home Assistant widgets. Before DeepSeek V4 Flash judges a result, it must pass Homarr's real clipboard parser, canonical schema, and deterministic scenario checks for the documented API routes, authentication, bindings, actions, and essential runtime components. It saves every response, validated widget manifest, and detailed category scores under `packages/custom-widgets/.ai-evaluations/`.
|
||||
|
||||
The run has a hard budget of ten generation attempts across all scenarios. Override the models or budget with `OPENROUTER_GENERATOR_MODEL`, `OPENROUTER_JUDGE_MODEL`, and `CUSTOM_WIDGET_AI_MAX_LOOPS`. Generated artifacts are local and ignored by Git; promote a reviewed, validated result into the bundled-widget source deliberately.
|
||||
Each scenario stops as soon as it passes and has a hard limit of ten generation attempts. Override the models or
|
||||
per-scenario limit with `OPENROUTER_GENERATOR_MODEL`, `OPENROUTER_JUDGE_MODEL`, and
|
||||
`CUSTOM_WIDGET_AI_MAX_LOOPS`. Generated artifacts are local and ignored by Git; promote a reviewed, validated result
|
||||
into the bundled-widget source deliberately.
|
||||
|
||||
The reference API check uses a real PokeAPI list/detail request and a read-only Portainer container query when `PORTAINER_BASE_URL` and `PORTAINER_API_KEY` are set. Use `pnpm --filter @homarr/custom-widgets test:reference-apis -- --pokeapi-only` for the public PokeAPI check alone. To exercise start, restart, and stop against a disposable container, also set `PORTAINER_TEST_CONTAINER_ID` and the explicit safeguard `PORTAINER_ALLOW_MUTATIONS=1`; the script restores the container's original running state.
|
||||
@@ -27,11 +27,12 @@ Every option has a default. Supported controls include text, textarea, number, s
|
||||
|
||||
Enter the desired widget and optional API documentation URL, then select **Copy AI prompt**. The single self-contained prompt is below 12,000 characters, starts with your request, includes the lean contract and two polished examples, and never claims that an offline chat has MCP tools.
|
||||
|
||||
The model must return exactly:
|
||||
The model must return one fenced `json` block containing the complete widget, including the JSX in its `template`
|
||||
field. Copy that single block and select **Paste AI response**. Homarr fills the visual builders and the JSX editor
|
||||
without any placeholder replacement or second paste.
|
||||
|
||||
1. One fenced `json` block with `template: "__HOMARR_TEMPLATE__"`.
|
||||
2. One fenced `jsx` block with the readable template.
|
||||
|
||||
Select **Paste AI response**. Homarr fills the visual builders and shows all actionable schema or JSX errors inline. Enter credentials separately. The prompt deliberately recommends a focused Mantine component set, visual hierarchy, responsive layout, theme compatibility, and loading, empty, failure, and success states.
|
||||
Homarr shows all actionable schema or JSX errors inline. Enter credentials separately. The prompt deliberately
|
||||
recommends a focused Mantine component set, visual hierarchy, responsive layout, theme compatibility, and loading,
|
||||
empty, failure, and success states.
|
||||
|
||||
Connected agents should use the skills.sh skill and retrieve the live schema and individual component metadata only as needed.
|
||||
@@ -38,7 +38,8 @@ Bounded regex literals are supported for string matching, splitting, search, and
|
||||
|
||||
- `SubFetch` runs a manual query with its `params`. Set `triggerContent` to a card or image to make that content the accessible click and keyboard trigger instead of showing the default load button.
|
||||
- `ActionButton` and `ToggleSwitch` run actions.
|
||||
- `RefreshButton` renders a compact, accessible icon control that refreshes load queries.
|
||||
- `RefreshButton` renders a compact, accessible icon control that refreshes load queries for authenticated viewers. It
|
||||
is disabled for anonymous public-board viewers because refreshing invalidates shared server cache state.
|
||||
- `Icon`/`TablerIcon` resolves installed safe icons.
|
||||
|
||||
Always include responsive loading, empty, error, and success states. Runtime failures remain inside the widget tile.
|
||||
@@ -49,6 +49,21 @@ interface HomarrCustomWidgetV2 {
|
||||
|
||||
The browser renders JSX. Homarr's server executes named requests, applies board permissions and network protections, and injects credentials. The browser never receives source credentials.
|
||||
|
||||
## Permissions
|
||||
|
||||
Custom Widget management is an administrator-only surface. Only a Homarr administrator can create, import, migrate,
|
||||
preview, publish, install, configure, or write secrets, including through HTTP authoring resources or MCP. An API key
|
||||
only lists Custom Widget MCP tools, prompts, and resources when its owner is an administrator.
|
||||
|
||||
Adding or configuring a Custom Widget placement requires both administrator access and permission to modify that
|
||||
board. A non-administrator with board-modify access can move, resize, change presentation settings, or remove an
|
||||
existing placement, but cannot add one, change its definition, refresh interval, or Custom Widget options. Duplicating
|
||||
a board that contains Custom Widgets also requires an administrator.
|
||||
|
||||
Once an administrator has placed a widget, ordinary board permissions apply to rendering and requests. Authorized
|
||||
non-administrators can use it on private boards, and queries can render for anonymous viewers on public boards.
|
||||
Mutations remain authenticated and enforce each request's view, modify, or full permission.
|
||||
|
||||
## Authoring paths
|
||||
|
||||
- [Create a Custom Widget](./authoring) visually or with one copied AI prompt.
|
||||
@@ -60,9 +75,26 @@ The browser renders JSX. Homarr's server executes named requests, applies board
|
||||
|
||||
The workbench keeps one continuous layout with visual source, request, and option editors. Advanced raw JSON remains available for experts and AI paste. Invalid values stay inline and disable both preview and Save/Create until they are corrected.
|
||||
|
||||
Exports, imports, Workshop, MCP, and storage all validate the same schema. Widgets saved in the legacy format remain visible with a **Migration required** badge after upgrading. Use **Copy migration prompt**, give the redacted prompt to an LLM, then import its v2 JSON from that widget's action menu. Homarr keeps the legacy record until the replacement validates and is confirmed; credentials are never included in the prompt.
|
||||
Exports, imports, the official Workshop client, and MCP validate the same schema. PocketBase stores community
|
||||
submissions without interpreting their content, and Homarr validates them before installation. Widgets saved in the v1
|
||||
format remain visible to administrators with a **Migration required** badge after upgrading. Use **Copy migration
|
||||
prompt**, give the redacted prompt to an LLM, copy its single complete JSON block, then select **Paste migrated widget**
|
||||
from that widget's action menu. Homarr reads the `template` value into the JSX editor automatically. The prompt keeps safe
|
||||
request metadata but deliberately omits the v1 display configuration because legacy free-text and JSX can contain
|
||||
hard-coded credentials. Add a credential-free description of the widget's visible layout and behavior when sending the
|
||||
prompt.
|
||||
|
||||
When adding widgets while editing a board, the Custom Widgets section always includes **Install from Workshop**. The Workshop and API source review open above the widget picker without closing it. After import, the new definition appears in the picker. Its tile waits for the board to be saved before server requests run and loads automatically after a successful save; no page reload is required.
|
||||
Homarr keeps the original v1 definition and encrypted secret as a compatibility backup even after the validated v2
|
||||
replacement is created. The v2 record uses the same stable ID and takes precedence. The archived v1 copy stays hidden
|
||||
while the replacement exists; deleting the v2 record surfaces the v1 entry as migration-required again. Automatic
|
||||
legacy deletion is intentionally unavailable during v2 stabilization. Credentials are never included in prompts,
|
||||
logs, or exports.
|
||||
|
||||
For administrators adding widgets while editing a board, the Custom Widgets section includes **Install from
|
||||
Workshop**. Non-administrators do not see the Custom Widget picker or Workshop actions. The Workshop and API source
|
||||
review open above the widget picker without closing it. After import, the new definition appears in the picker. Its tile
|
||||
waits for the board to be saved before server requests run and loads automatically after a successful save; no page
|
||||
reload is required.
|
||||
|
||||
## Import and Workshop
|
||||
|
||||
@@ -70,10 +102,25 @@ Import review shows origins, authentication modes, network scopes, methods, acti
|
||||
|
||||
For example, installing **Tautulli Activity** asks for both the user's Tautulli URL and API key. A stable public source such as PokéAPI keeps its published URL without creating unnecessary setup work.
|
||||
|
||||
Workshop publishes technically valid widgets immediately; users can vote or report them, and administrators can delete submissions. Publishers should replace personal private-network hosts with a clear service placeholder before publishing.
|
||||
Workshop publishes technically valid widgets immediately; users can vote or report them, and Workshop moderators can
|
||||
delete submissions. Community moderation is separate from Homarr administration and is not a security boundary.
|
||||
Publishers should replace personal private-network hosts with a clear service placeholder before publishing. Homarr
|
||||
performs definitive validation again at install time.
|
||||
|
||||
Connected agents can search, inspect, and install Workshop widgets with `customWidget_workshopSearch`, `customWidget_workshopGet`, and `customWidget_workshopInstall`. After installation they can set a source URL and credentials with `customWidget_sourceConfigure`, or create a secure user-facing setup URL with `customWidget_configurationRequestUser`. Secret values are never returned through MCP.
|
||||
|
||||
These tools are only exposed to API keys owned by Homarr administrators. Opening and completing a source-configuration
|
||||
URL also requires the same authenticated administrator; the URL is short-lived, single-use, and redacted.
|
||||
|
||||
## Reliability and rollback
|
||||
|
||||
Custom Widget response caches and action invalidation use shared Redis state, so multiple Homarr replicas see the same
|
||||
versioned cache generation. Deployments must point every replica at the same Redis service.
|
||||
|
||||
Before upgrading, back up the database and `SECRET_ENCRYPTION_KEY`; a v1 binary can still read preserved v1 tables
|
||||
during application rollback. Widgets created only in v2 may be unavailable to the rolled-back binary, but do not
|
||||
replace the v1 backup.
|
||||
|
||||
## Bundled examples
|
||||
|
||||
Homarr seeds five disabled examples without credentials and never overwrites an edited seed. They use the same public contract. The Tautulli example is the highest-scoring widget preserved from Homarr's AI authoring evaluation:
|
||||
|
||||
@@ -12,7 +12,9 @@ Requests are keyed by ID. `source`, `kind`, `method`, `trigger`, `auth`, and `pe
|
||||
|
||||
The request `path` is appended to the source `baseUrl`, including a base path such as `/api/v2`.
|
||||
|
||||
GET, POST, PUT, PATCH, and DELETE work for queries and actions. Kind—not method—controls behavior. Load queries run automatically, manual queries run through `SubFetch`, and actions run only from `ActionButton` or `ToggleSwitch`.
|
||||
GET, POST, PUT, and PATCH work for queries and actions. DELETE is restricted to actions so it can never run while a
|
||||
board loads. Kind controls the remaining behavior: load queries run automatically, manual queries run through
|
||||
`SubFetch`, and actions run only from `ActionButton` or `ToggleSwitch`.
|
||||
|
||||
Bind values directly where they are used:
|
||||
|
||||
@@ -40,3 +42,12 @@ Paths and query-string values must resolve to text, numbers, or booleans. JSON b
|
||||
Every request uses Homarr's existing server executor: same-origin source enforcement, network scope, DNS and redirect validation, SSRF protection, board permissions, rate and request limits, body and response limits, timeouts, and encrypted credential injection. Static headers cannot override credentials, cookies, routing, proxy, forwarding, or hop-by-hop headers.
|
||||
|
||||
Queries default to view permission and actions to modify. DELETE always requires full permission and confirmation. Actions are never cached, retried, or run on load.
|
||||
|
||||
Management and runtime are intentionally separate. A Homarr administrator with board-modify permission places and
|
||||
configures the widget. After placement, query and action authorization follows the request's board permission. Public
|
||||
boards may execute queries for anonymous viewers, but mutations stay authenticated. This includes shared-cache
|
||||
invalidation: `RefreshButton` is disabled for anonymous viewers, while ordinary scheduled query rendering remains
|
||||
available.
|
||||
|
||||
Responses use bounded, versioned shared-Redis cache keys. Action invalidation advances the shared version so every
|
||||
Homarr replica stops serving the previous response without scanning or deleting a key prefix.
|
||||
@@ -4,7 +4,16 @@
|
||||
|
||||
The definition does not exist. If it was deleted, remove the unavailable tile from the board.
|
||||
|
||||
If the Custom Widgets page shows the definition with a **Migration required** badge, open its action menu and select **Copy migration prompt**. Give that redacted prompt to an LLM, then import the resulting v2 JSON from the same menu. Homarr keeps the legacy definition until the replacement validates and you confirm the migration.
|
||||
If the Custom Widgets page shows the definition with a **Migration required** badge, an administrator can open its
|
||||
action menu and select **Copy migration prompt**. Give that redacted prompt to an LLM, then import the resulting v2 JSON
|
||||
from the same menu. The LLM returns one complete JSON block; copy it once and select **Paste migrated widget**. Homarr
|
||||
places its `template` value into the JSX editor automatically. Because arbitrary v1 display text or JSX may contain
|
||||
credentials, the prompt omits that display configuration; describe the old widget's visible layout and behavior without
|
||||
including secrets. Other viewers see **Contact an administrator** instead of a migration link.
|
||||
|
||||
Homarr keeps the v1 definition and encrypted secret after migration. The validated v2 replacement uses the same ID and
|
||||
takes precedence; the archived v1 record reappears if the v2 replacement is deleted. There is no v1 permanent-delete
|
||||
action during the v2 stabilization period.
|
||||
|
||||
Otherwise, install or create a Custom JSX v2 definition.
|
||||
|
||||
@@ -34,6 +43,11 @@ An invalid definition disables widget preview and Save/Create. The Data, Options
|
||||
|
||||
The Diagnostics tab shows the current schema errors.
|
||||
|
||||
## Workshop unavailable
|
||||
|
||||
If Workshop is unavailable, check `WORKSHOP_API_URL` and PocketBase health. Widgets that are already installed continue
|
||||
to work.
|
||||
|
||||
## Correct request errors
|
||||
|
||||
Check the API source network scope. Check the base URL and credentials.
|
||||
@@ -44,6 +58,9 @@ For “invalid placeholder,” use `{option:name}` or `{param:name}`. Load queri
|
||||
|
||||
The journal shows the method, request ID, path template, status, and duration.
|
||||
|
||||
In a multi-instance deployment, all Homarr replicas must share Redis. Versioned cache invalidation is distributed
|
||||
through Redis; replicas connected to different Redis databases can serve stale query responses after an action.
|
||||
|
||||
## Correct a Mantine prop warning
|
||||
|
||||
`UNKNOWN_MANTINE_PROP` is a warning. Homarr passes the prop to Mantine.
|
||||
@@ -57,3 +74,10 @@ Use safe widget options, temporary inputs, or named requests instead.
|
||||
The widget option definitions changed and the saved values are invalid. Open the item settings.
|
||||
|
||||
Correct the marked configuration values. Homarr does not infer widget option migrations.
|
||||
|
||||
## Roll back safely
|
||||
|
||||
Before an application upgrade, back up the database and preserve the exact `SECRET_ENCRYPTION_KEY`. The v2 schema keeps
|
||||
the physical v1 definition and secret tables readable by a v1 binary. Roll back the application without running
|
||||
manual cleanup, verify legacy widgets, and restore the database backup if the migration itself must be reversed.
|
||||
PocketBase Workshop data is a separate backup and restore operation.
|
||||
Reference in new issue
Block a user