Plugwerk 1.0.0-beta.3

Released: 2026-05-10 · GitHub release · Docker image

The third beta brings a complete transactional-email pipeline (SMTP backend, admin templates, Mailpit profile for local development), self-service user registration with forgot-password / reset-password flows, a sweep of security and performance fixes, and small but real breaking changes on the Client SDK that downstream hosts will want to plan for.

Highlights

• Transactional email infrastructure — SMTP backend, admin pages for SMTP configuration and email-template management, an editorial-minimal HTML layout for outgoing mail, and an opt-in Mailpit profile so local development gets a catch-all inbox without external SMTP.
• Self-service registration — application-setting gated. Operators can enable a public sign-up flow with email verification.
• Forgot-password / reset-password — same gating model. End users recover access without an admin round-trip when the setting is on.
• Superadmin-triggered password reset — admins can send a reset email to any user from the user-admin UI; the user then completes the reset themselves.
• Catalog correctness for the Client SDK — PlugwerkCatalog now walks every server page in list / search / releases, so paginated catalogs no longer truncate at the first page.
• Mailpit local SMTP catch-all — docker compose --profile mail up -d brings up a one-process inbox at http://localhost:8025 that the server can talk to over plain SMTP, no external account required.

Breaking changes

• Client SDK — PlugwerkInstaller now drives the PF4J PluginManager lifecycle. The installer takes ownership of loadPlugin / startPlugin / unloadPlugin, removing the older lifecycle-wrapper indirection that some hosts had to mirror manually. Hosts that hand-rolled the plugin lifecycle around the SDK will need to drop their wrapper. The follow-up SDK reference docs are tracked in website#83.
• Client SDK — connect() now threads the PluginManager so the deprecated PF4J wrapper can be retired. The new shape is documented in Client Plugin → Configuration.
• /api/v1/admin/users is now paginated. Anyone consuming the endpoint via raw HTTP needs to honour the new pagination wrapper. The Admin UI handles this transparently.
• OIDC client-secret encryption switched from AES-CBC to AES-GCM. The on-disk format is upgraded transparently the first time a secret is read or rotated; no operator action required, but secrets stored under the previous scheme are re-encrypted opportunistically. Plan for a small one-time write amplification on first reads after the upgrade.
• JWTs without jti, sub, or iat are now rejected with a clear error. Hand-rolled test tokens that omitted any of these will start failing — regenerate them.

Upgrade notes

1. Pull the new image:

   docker pull plugwerk/plugwerk-server:1.0.0-beta.3

2. Audit any custom integrations against the breaking-change list above. The Client SDK changes are the most likely to affect a live deployment; the JWT / pagination changes only affect raw integrators.

3. Decide whether to enable the new application settings.

   • Self-service registration — off by default. Enable from the admin settings page once you have decided whether it fits your access model.
   • Forgot-password / reset-password — off by default; enable in the admin settings page. Requires SMTP to be configured first.

4. Configure SMTP if you want any of the email-driven features (registration verification, password reset, superadmin-triggered reset). Use Admin → Email → SMTP in the web UI, or in development the new Mailpit profile:

   docker compose --profile mail up -d
   # Mailpit web UI at http://localhost:8025

5. Verify the upgrade:

   • curl http://<your-host>/actuator/health returns {"status":"UP"}.
   • Existing users can still log in (their refresh cookies survive the upgrade).
   • Admin → Email → Templates lists the bundled templates.

Other notable changes

Security

• SSRF guard for OIDC discovery and stored URIs — the server refuses to talk to private-network or link-local addresses when probing or refreshing an issuer URI.
• Defense-in-depth @PreAuthorize sweep across admin list endpoints — closes a handful of cases where the route handler was the only authorization gate.
• Constant-time padding on the forgot-password 204 response — the handler now takes a fixed minimum time regardless of whether the email exists, removing a timing oracle.
• Multiple dependency CVEs cleared — axios bumped through 13 advisories, postcss bumped to clear CVE-2026-41305, yaml bumped to clear CVE-2026-33532.

Performance

• N+1 query fix in UpdateCheckService — the client update poll for hosts with large installed-plugin sets is now a small, bounded number of queries instead of one per plugin.
• Pagination on /admin/users with optional server-side search via the q query parameter — the previous unbounded list could time out on large installations.
• Storage I/O moved out of @Transactional boundaries in delete paths — long-running storage deletes no longer hold a database transaction open.
• Deterministic latest-release picking per plugin in the catalog — fixes a non-deterministic ordering on simultaneous publishes that occasionally surfaced an older release as "latest".

Bug fixes

• @RequestParam constraint violations now return HTTP 400 instead of 500 — proper input-validation semantics on the affected endpoints.
• Settings cache refresh deferred until after transaction commit — fixes a race where a partially-applied settings update could be observed by other threads.
• Public response shape for the catalog list endpoint stabilised — internal-only fields are no longer leaked.

Developer experience

• MUI Material v7 → v9 frontend migration — only relevant if you fork the admin frontend.
• Self-hosted Renovate for the main repo (operator-invisible).

Full changelog

See the GitHub release notes for the complete commit-level changelog and individual PR links.