@askalf/dario 5.5.0 → 5.5.1

package/dist/health-response.d.ts

@@ -110,18 +110,21 @@ export declare function probeRequested(url: string | undefined): boolean;
  * Deliberately stricter than shouldDiscloseHealthInternals, because this is
  * not a disclosure decision — it spends the operator's money.
  *
- * The disclosure gate treats "authenticated" as sufficient, and
- * `authenticateRequest` returns TRUE when no DARIO_API_KEY is configured at
- * all. That is a reasonable convenience for the common loopback setup, and
- * harmless for a read-only field. It is not harmless here: an unkeyed dario
- * published through a Cloudflare tunnel would otherwise expose `?probe=1` as a
- * button any anonymous caller could press to bill the operator, once per TTL,
- * forever.
+ * The disclosure gate grants access to a caller that proved a configured
+ * DARIO_API_KEY, wherever it came from. That is the right answer for reading a
+ * field. It is not the right answer for an action that bills per call: a
+ * leaked or shared key becomes a metered spend endpoint reachable from the
+ * public internet, and the probe's own cache means an attacker needs only one
+ * request per TTL to keep it running indefinitely.
  *
  * So the probe additionally refuses anything that arrived through the tunnel,
- * whatever `authenticated` says. This only ever DENIES — it cannot widen
- * access — and it makes the spend path independent of whether an API key
- * happens to be configured.
+ * whatever the disclosure gate concluded. This only ever DENIES — it cannot
+ * widen access.
+ *
+ * (An unkeyed proxy is handled a layer up: shouldDiscloseHealthInternals now
+ * requires `keyConfigured`, so vacuous authentication no longer reaches here
+ * at all. This gate does not depend on that fix — it would refuse the tunnel
+ * caller either way — but the two are the same defence at different depths.)
  *
  * Accepted trade-off: an operator who authenticates THROUGH the tunnel is also
  * refused, and has to probe from beside the proxy instead. For a flag whose
@@ -137,16 +140,40 @@ export declare function shouldRunServingProbe(opts: {
  *
  * /health is intentionally auth-free (docker healthchecks need it before a
  * key is configured), so we cannot simply gate on the API key. Trust model:
- *   - authenticated (valid DARIO_API_KEY)      -> internal (an internal caller)
+ *   - PROVED a configured DARIO_API_KEY        -> internal (an internal caller)
  *   - came via the Cloudflare tunnel (cf-ray)  -> public   (world-reachable)
  *   - otherwise bare loopback                  -> internal (docker HC / doctor)
  *   - otherwise (LAN, other container, WAN)    -> public
- * The cf-ray check is now only ever used to DENY (force public), never to
- * grant, so spoofing it cannot widen disclosure — the previous fail-open
- * direction is closed.
+ * The cf-ray check is only ever used to DENY (force public), never to grant,
+ * so spoofing it cannot widen disclosure.
+ *
+ * `keyConfigured` is load-bearing and is why `authenticated` alone is not
+ * enough. `authenticateRequest()` short-circuits to TRUE when no
+ * DARIO_API_KEY is set — a deliberate convenience, since the common setup is
+ * loopback-only and requiring a key there would break `dario doctor` and every
+ * docker healthcheck. But it means "authenticated" is VACUOUS on an unkeyed
+ * proxy: every caller satisfies it, the first branch returns before cf-ray is
+ * ever consulted, and an unkeyed dario published through a Cloudflare tunnel
+ * hands its OAuth countdown, request volume and refresh-failure count to
+ * anyone who asks. That is the #642 fail-open re-entering through a side door
+ * — #642 closed the spoofable-header direction, not this one.
+ *
+ * Requiring both means the auth branch can only be taken by a caller that
+ * actually presented the operator's secret. Unkeyed proxies fall through to
+ * the transport rules, where loopback is still trusted (healthchecks and
+ * doctor keep working, unchanged) and the tunnel is not.
+ *
+ * `keyConfigured` is a REQUIRED field rather than an optional with a default:
+ * for a security predicate, every call site should be forced to state it.
+ *
+ * The HTTP status (200/503) is unaffected either way, so uptime monitoring
+ * that keys on the status code sees no change from this.
  */
 export declare function shouldDiscloseHealthInternals(opts: {
+    /** Passed authenticateRequest — which is vacuously true when unkeyed. */
     authenticated: boolean;
+    /** Whether a DARIO_API_KEY exists at all, i.e. whether `authenticated` means anything. */
+    keyConfigured: boolean;
     loopback: boolean;
     viaCfRay: boolean;
 }): boolean;

package/dist/health-response.js

@@ -133,18 +133,21 @@ export function probeRequested(url) {
  * Deliberately stricter than shouldDiscloseHealthInternals, because this is
  * not a disclosure decision — it spends the operator's money.
  *
- * The disclosure gate treats "authenticated" as sufficient, and
- * `authenticateRequest` returns TRUE when no DARIO_API_KEY is configured at
- * all. That is a reasonable convenience for the common loopback setup, and
- * harmless for a read-only field. It is not harmless here: an unkeyed dario
- * published through a Cloudflare tunnel would otherwise expose `?probe=1` as a
- * button any anonymous caller could press to bill the operator, once per TTL,
- * forever.
+ * The disclosure gate grants access to a caller that proved a configured
+ * DARIO_API_KEY, wherever it came from. That is the right answer for reading a
+ * field. It is not the right answer for an action that bills per call: a
+ * leaked or shared key becomes a metered spend endpoint reachable from the
+ * public internet, and the probe's own cache means an attacker needs only one
+ * request per TTL to keep it running indefinitely.
  *
  * So the probe additionally refuses anything that arrived through the tunnel,
- * whatever `authenticated` says. This only ever DENIES — it cannot widen
- * access — and it makes the spend path independent of whether an API key
- * happens to be configured.
+ * whatever the disclosure gate concluded. This only ever DENIES — it cannot
+ * widen access.
+ *
+ * (An unkeyed proxy is handled a layer up: shouldDiscloseHealthInternals now
+ * requires `keyConfigured`, so vacuous authentication no longer reaches here
+ * at all. This gate does not depend on that fix — it would refuse the tunnel
+ * caller either way — but the two are the same defence at different depths.)
  *
  * Accepted trade-off: an operator who authenticates THROUGH the tunnel is also
  * refused, and has to probe from beside the proxy instead. For a flag whose
@@ -162,16 +165,37 @@ export function shouldRunServingProbe(opts) {
  *
  * /health is intentionally auth-free (docker healthchecks need it before a
  * key is configured), so we cannot simply gate on the API key. Trust model:
- *   - authenticated (valid DARIO_API_KEY)      -> internal (an internal caller)
+ *   - PROVED a configured DARIO_API_KEY        -> internal (an internal caller)
  *   - came via the Cloudflare tunnel (cf-ray)  -> public   (world-reachable)
  *   - otherwise bare loopback                  -> internal (docker HC / doctor)
  *   - otherwise (LAN, other container, WAN)    -> public
- * The cf-ray check is now only ever used to DENY (force public), never to
- * grant, so spoofing it cannot widen disclosure — the previous fail-open
- * direction is closed.
+ * The cf-ray check is only ever used to DENY (force public), never to grant,
+ * so spoofing it cannot widen disclosure.
+ *
+ * `keyConfigured` is load-bearing and is why `authenticated` alone is not
+ * enough. `authenticateRequest()` short-circuits to TRUE when no
+ * DARIO_API_KEY is set — a deliberate convenience, since the common setup is
+ * loopback-only and requiring a key there would break `dario doctor` and every
+ * docker healthcheck. But it means "authenticated" is VACUOUS on an unkeyed
+ * proxy: every caller satisfies it, the first branch returns before cf-ray is
+ * ever consulted, and an unkeyed dario published through a Cloudflare tunnel
+ * hands its OAuth countdown, request volume and refresh-failure count to
+ * anyone who asks. That is the #642 fail-open re-entering through a side door
+ * — #642 closed the spoofable-header direction, not this one.
+ *
+ * Requiring both means the auth branch can only be taken by a caller that
+ * actually presented the operator's secret. Unkeyed proxies fall through to
+ * the transport rules, where loopback is still trusted (healthchecks and
+ * doctor keep working, unchanged) and the tunnel is not.
+ *
+ * `keyConfigured` is a REQUIRED field rather than an optional with a default:
+ * for a security predicate, every call site should be forced to state it.
+ *
+ * The HTTP status (200/503) is unaffected either way, so uptime monitoring
+ * that keys on the status code sees no change from this.
  */
 export function shouldDiscloseHealthInternals(opts) {
-    if (opts.authenticated)
+    if (opts.authenticated && opts.keyConfigured)
         return true;
     if (opts.viaCfRay)
         return false;

package/dist/proxy.js

@@ -1701,6 +1701,9 @@ export async function startProxy(opts = {}) {
             const viaCfRay = req.headers['cf-ray'] !== undefined;
             const includeInternal = shouldDiscloseHealthInternals({
                 authenticated: authenticateRequest(req.headers, apiKeyBuf),
+                // Without this, `authenticated` is vacuously true on an unkeyed proxy
+                // and the tunnel check below is never reached — see the gate's docs.
+                keyConfigured: apiKeyBuf !== null,
                 loopback: isLoopbackAddr(req.socket?.remoteAddress),
                 viaCfRay,
             });

package/docs/usage.md

@@ -150,9 +150,10 @@ Notes that matter in production:
 
 - **The probe is opt-in and never runs on a plain `/health`.** Existing docker
   healthchecks and uptime monitors keep costing nothing.
-- **Only trusted callers can trigger it** — authenticated, or loopback that did
-  not arrive through a Cloudflare tunnel (the same gate that governs the OAuth
-  internals). A world-readable `/health` is not a button for spending tokens.
+- **Only trusted callers can trigger it** — and never a caller that arrived
+  through a Cloudflare tunnel, even an authenticated one. A `/health` reachable
+  from the internet is not a button for spending tokens, and the probe's own
+  cache means one request per TTL would be enough to keep it running.
 - **Results are cached and single-flighted** (`DARIO_PROBE_TTL_MS`, default
   60000), so polling every second still costs at most one probe per minute.
 - **A rate-limited or overloaded upstream is not an outage.** 429 and 529 keep
@@ -164,6 +165,27 @@ Notes that matter in production:
   failure mode in dario#905 was slots that stopped turning over entirely. Any
   release resets the stall clock, so sustained load never trips it.
 
+### Who sees what
+
+`/health` is auth-free by design — a docker healthcheck has to work before any
+key is configured. The response body is therefore split two ways, while the HTTP
+status (200/503) is identical for everyone, so uptime checks are unaffected:
+
+| Caller | Gets |
+|---|---|
+| Presented a configured `DARIO_API_KEY` | full detail |
+| Bare loopback (docker healthcheck, `dario doctor`) | full detail |
+| Arrived through a Cloudflare tunnel (`cf-ray`) | `{"status": "ok"}` only |
+| Anything else (LAN, another container, WAN) | `{"status": "ok"}` only |
+
+> **Changed in 5.5.1.** "Presented a configured key" previously read as "passed
+> the API-key check" — which every caller passes when **no** `DARIO_API_KEY` is
+> set. On an unkeyed proxy published through a tunnel, that disclosed the OAuth
+> countdown, request volume and refresh-failure count to anyone who asked. If
+> you monitor `/health` through a tunnel with no key configured, you now get the
+> liveness verdict only; set `DARIO_API_KEY` and send it, or query from
+> loopback, to keep the detail.
+
 A watchdog wants the probe; a container healthcheck usually does not:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "5.5.0",
+  "version": "5.5.1",
   "description": "Use your Claude Pro/Max subscription in any tool — Cursor, Cline, Aider, the Agent SDK, your scripts — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint.",
   "type": "module",
   "bin": {