feat(dockhand): support API token (Bearer) authentication

Dockhand added user-scoped API token auth in v1.0.25, but the widget only
supported local username/password login. Storing full account credentials in
services.yaml is heavier than needed for a read-only status widget.

Add an optional `key` that is sent as `Authorization: Bearer <key>`. When set,
it takes precedence over username/password and the 401 session-login fallback is
skipped (a 401 with a token means the token itself is invalid). The existing
username/password flow is unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: jheaton141

docs/widgets/services/dockhand.md

@@ -5,11 +5,23 @@ description: Dockhand Widget Configuration
 
 Learn more about [Dockhand](https://dockhand.pro/).
 
-Note: The widget currently supports Dockhand's **local** authentication only.
+Authenticate with either a Dockhand [API token](https://dockhand.pro/manual/#api-authentication) (recommended) or Dockhand's local username/password. A token is scoped to the user that created it and can be revoked without changing your password, so it's preferable to storing account credentials in your config. If both are provided, the token is used.
 
 **Allowed fields:** (max 4): `running`, `stopped`, `paused`, `total`, `cpu`, `memory`, `images`, `volumes`, `events_today`, `pending_updates`, `stacks`.
 **Default fields:** `running`, `total`, `cpu`, `memory`.
 
+Using an API token:
+
+```yaml
+widget:
+  type: dockhand
+  url: http://localhost:3001
+  environment: local # optional: name or id; aggregates all when omitted
+  key: dockhandapitoken # generate under Settings in Dockhand
+```
+
+Using local authentication:
+
 ```yaml
 widget:
   type: dockhand

src/widgets/dockhand/proxy.js

@@ -38,12 +38,18 @@ export default async function dockhandProxyHandler(req, res) {
 
   const url = new URL(formatApiCall(widgets[widget.type].api, { endpoint, ...widget }));
 
+  // A Dockhand API token (Bearer) takes precedence over username/password. See
+  // https://dockhand.pro/manual/#api-authentication
+  const headers = widget.key ? { Authorization: `Bearer ${widget.key}` } : {};
+
   let [status, contentType, data] = await httpProxy(url, {
     method: req.method,
+    headers,
   });
 
-  // Attempt login and retrying once
-  if (status === 401) {
+  // Fall back to a username/password session login and retry once. Skipped when a
+  // token is configured, since a 401 there means the token itself is invalid.
+  if (status === 401 && !widget.key) {
     const loggedIn = await login(widget);
     if (loggedIn) {
       [status, contentType, data] = await httpProxy(url, {

src/widgets/dockhand/proxy.test.js

@@ -59,6 +59,45 @@ describe("widgets/dockhand/proxy", () => {
     expect(res.body).toEqual(Buffer.from("data"));
   });
 
+  it("sends a bearer token and does not log in when a key is configured", async () => {
+    getServiceWidget.mockResolvedValue({
+      type: "dockhand",
+      url: "http://dockhand/",
+      key: "dh_abc123",
+    });
+
+    httpProxy.mockResolvedValueOnce([200, "application/json", Buffer.from("data")]);
+
+    const req = { method: "GET", query: { group: "g", service: "svc", endpoint: "api/v1/status", index: "0" } };
+    const res = createMockRes();
+
+    await dockhandProxyHandler(req, res);
+
+    expect(httpProxy).toHaveBeenCalledTimes(1);
+    expect(httpProxy.mock.calls[0][1].headers).toEqual({ Authorization: "Bearer dh_abc123" });
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toEqual(Buffer.from("data"));
+  });
+
+  it("does not fall back to login on a 401 when a key is configured", async () => {
+    getServiceWidget.mockResolvedValue({
+      type: "dockhand",
+      url: "http://dockhand/",
+      key: "dh_bad",
+    });
+
+    httpProxy.mockResolvedValueOnce([401, "application/json", Buffer.from("nope")]);
+
+    const req = { method: "GET", query: { group: "g", service: "svc", endpoint: "api/v1/status", index: "0" } };
+    const res = createMockRes();
+
+    await dockhandProxyHandler(req, res);
+
+    // Only the initial request — no login attempt, no retry.
+    expect(httpProxy).toHaveBeenCalledTimes(1);
+    expect(res.statusCode).toBe(401);
+  });
+
   it("returns a sanitized error response for HTTP errors", async () => {
     getServiceWidget.mockResolvedValue({
       type: "dockhand",