iit-mcp-hudu 0.1.0 → 0.2.1

package/.env.example

@@ -17,6 +17,32 @@ MCP_TRANSPORT=stdio
 #        WITHOUT its own key runs as this key, so set it only when that is intended. It is only ever
 #        sent to HUDU_BASE_URL, never to a caller-named origin. Left commented so a copied example
 #        does not set an empty value.
+#
+# HOW TO LOAD THIS FILE -- read before the first live call.
+# ---------------------------------------------------------------------------------------------
+# Source it with a shell, which is what consumes the single quotes the values below are written in:
+#
+#     set -a; . ./.env; set +a
+#
+# Do NOT use a quote-preserving dotenv parser (a plain KEY=VALUE split that keeps the quotes) on
+# this file. It hands `'...'` -- quotes included -- to the server, and Hudu answers 401 for a
+# credential that was never wrong. The trap is sharpest when the secret contains `$`:
+# HUDU_API_KEY='a$b' is `a$b` when sourced and `'a$b'` when naively parsed, and both look correct
+# in the file. A wrong credential is a real authentication failure against your Hudu account, and
+# repeated ones risk an account lock.
+#
+# Then run the zero-wire preflight before any live session:
+#
+#     npx -y iit-mcp-hudu doctor        # or: node dist/main.js doctor
+#
+# It prints length + two-character prefix + shapeOk per credential field (never a value) and dials
+# nothing, and exits non-zero when the credential would be refused. CONTRACT: a green doctor makes
+# any later 401 vendor-side (rotated, revoked or role-restricted key) -- stop and check the vendor
+# rather than re-dialing.
+#
+# The server enforces the same shape anyway: preserved surrounding quotes, an embedded quote, a
+# carriage return, a newline, edge whitespace or a NUL byte in the value fails boot for
+# HUDU_API_KEY, and is refused with CREDENTIAL_MALFORMED for a per-request X-Hudu-Api-Key.
 # HUDU_API_KEY=
 
 # http only, optional. Hosts a caller may name in X-Hudu-Base-Url: comma-separated exact hostnames or
@@ -62,6 +88,24 @@ LOG_LEVEL=info
 # articles and caps assets at ~4,000.
 HUDU_SEARCH_MAX_INDEX_PAGES=40
 
+# The read-through cache the SDK clients use (SDK 0.12.0). on (the default) selects the SDK's
+# per-entity TTL preset (1 h structural / 5 min mutable / 1 min base): repeated reads of the
+# same record are served from the cache until the TTL expires. off disables it: every read
+# re-dials Hudu.
+# HUDU_CACHE_PRESET=on
+
+# The 429 cooldown gate (SDK 0.12.0). on (the default) arms a local deadline after a vendor
+# 429 whose retries are spent (the profile's 1 retry: the first such call dials twice): calls
+# the gate refuses are answered locally with notSent: true, never re-dialed. off
+# retries a 429 per the agent profile's retry budget instead of arming a local deadline.
+# HUDU_COOLDOWN=on
+
+# The whole-call deadline in milliseconds (SDK 0.12.0). Must be a positive integer. Defaults
+# to 30000 and is always sent to the SDK explicitly, so it stays above the agent profile's
+# 20 s deadline regardless of preset: the default keeps the tolerance a cold tier:'index'
+# body-index walk had before the 0.12.0 adoption.
+# HUDU_TIMEOUT_MS=30000
+
 # The resources hudu_search and hudu_resolve_any may offer and query. Unset means the SDK's full
 # searchable set (articles, asset_passwords, assets, companies, groups, password_folders, users,
 # websites). Set it to the subset THIS deployment's Hudu API key can read, so a tool neither

package/README.md

@@ -4,9 +4,10 @@ MCP server for Hudu IT documentation, built on the [`node-hudu`](https://www.npm
 
 ## Tool surface
 
-19 tools by default: `hudu_list_operations`, `hudu_describe_operation`, `hudu_read`, twelve
-core reads, and four bounded list reads. Setting `HUDU_READ_ONLY=false` adds `hudu_write` and
-`hudu_delete` (21 tools). Each dispatcher uses a separate SDK client in its matching mode,
+20 tools by default: `hudu_list_operations`, `hudu_describe_operation`, `hudu_read`,
+`hudu_fetch_many`, twelve core reads, and four bounded list reads. Setting
+`HUDU_READ_ONLY=false` adds `hudu_write` and `hudu_delete` (22 tools). Each dispatcher uses a
+separate SDK client in its matching mode,
 with names, annotations and operation enums from the SDK's curated metadata. SDK enforcement
 rejects cross-effect calls before requests. The old `hudu_invoke`, `hudu_catalog` and
 `hudu_describe` names are removed; consumers must resync their tool catalog.
@@ -24,6 +25,18 @@ request; `asset_layouts` is not searchable (the SDK declares no vendor text filt
 `hudu_list_asset_layouts` follows the same reachability as the existing ungated
 `hudu_get_asset_layout` tool.
 
+These tools run on node-hudu 0.13.1; the `SDK behaviour (0.12.0)` section below covers the behaviours that shape them: redirect refusal, the closed input contract, the error envelope, and the client opt-ins. Numeric ids must be positive integers on every tool; anything else is refused before a request is made.
+
+`hudu_fetch_many` (node-hudu 0.12.0) fetches up to 20 single records across mixed resources in
+one call: each item is exactly `{ resource, id, fields? }` — one of the 22 bare-id resources, a
+numeric vendor id, and an optional client-side field projection. A shape violation is refused at
+the schema layer before any request, and failure is per-item: a miss or a vendor fault lands on
+its own row as a typed error while the rest of the batch is served. The deployment's secret-read
+policy applies to the batch's items exactly as to a single read, so a credential item is
+refused pre-request under the default `HUDU_SECRET_READS=deny`; `HUDU_READ_ONLY` keeps the tool
+— it is a read. The same batch stays reachable through `hudu_read` with operation
+`operations.fetchMany`, gated the same way.
+
 ## Transports
 
 | Transport | For | Caller auth | Hudu credential |
@@ -36,21 +49,12 @@ request; `asset_layouts` is not searchable (the SDK declares no vendor text filt
 Needs Node 24+, a Hudu API key and your Hudu origin. `stdio` is the default transport, so no
 `MCP_TRANSPORT` is needed. Mutation tools stay off unless you set `HUDU_READ_ONLY=false`.
 
-**From a clone:**
-
-```
-git clone https://github.com/msoukhomlinov/iit-mcp-hudu.git
-cd iit-mcp-hudu
-npm install
-npm run build
-```
-
-Then register `dist/main.js` with your client, e.g. Claude Code:
+**From npm** (recommended):
 
 ```
 claude mcp add hudu \
   --env HUDU_API_KEY=your-key --env HUDU_BASE_URL=https://your.hudu.host \
-  -- node /absolute/path/to/iit-mcp-hudu/dist/main.js
+  -- npx -y iit-mcp-hudu
 ```
 
 or in `.mcp.json` / Claude Desktop config:
@@ -59,23 +63,70 @@ or in `.mcp.json` / Claude Desktop config:
 {
   "mcpServers": {
     "hudu": {
-      "command": "node",
-      "args": ["/absolute/path/to/iit-mcp-hudu/dist/main.js"],
+      "command": "npx",
+      "args": ["-y", "iit-mcp-hudu"],
       "env": { "HUDU_API_KEY": "your-key", "HUDU_BASE_URL": "https://your.hudu.host" }
     }
   }
 }
 ```
 
-**From npm:**
+`npx` fetches the package on first run and caches it; use `iit-mcp-hudu@<version>` to pin one.
+
+**From a clone** (for development): see [Development](#development). Point your client at
+`node /absolute/path/to/iit-mcp-hudu/dist/main.js` after `npm run build`.
+
+## Loading credential values (read this before a live session)
+
+A Hudu credential whose bytes reach this server mangled costs a real authentication failure against
+your Hudu account, and repeated ones risk an account lock. Two rules keep that from happening.
+
+**Load an env file the way the file documents — shell sourcing, not a generic dotenv parse.**
 
 ```
-claude mcp add hudu \
-  --env HUDU_API_KEY=your-key --env HUDU_BASE_URL=https://your.hudu.host \
-  -- npx -y iit-mcp-hudu
+set -a; . ./.env; set +a      # the .env.example recipe, for a file of single-quoted values
 ```
 
-or `"command": "npx", "args": ["-y", "iit-mcp-hudu"]` in the JSON config above.
+`.env.example` writes its example values in single quotes, which is the normal `.env` style. A
+**shell** consumes those quotes when the file is sourced, so the value the process sees is exactly
+the secret. A **quote-preserving dotenv parser** (`dotenv`-style `KEY=VALUE` splitting that keeps
+the quotes) does not: it hands `'…'` to the server, quotes included, and the vendor rejects it.
+The trap is sharpest when the secret itself contains `$` — `HUDU_API_KEY='a$b'` becomes `a$b` when
+sourced and `'a$b'` (with quotes) when naively parsed, and both look correct in the file.
+
+The client-config and `--env` paths shown under *Local use* pass values verbatim and never parse a
+file, so they are already safe — this rule is for anyone loading a `.env`.
+
+**Run `doctor` before the first live call.** It answers "did my credential load intact?" from the
+environment alone, with zero Hudu requests:
+
+```
+npx -y iit-mcp-hudu doctor     # or: node dist/main.js doctor
+```
+
+It prints, per credential field, the value's `length`, its two-character `prefix2` and a `shapeOk`
+flag with the anomaly names when it is not; plus the origin that will actually be dialed. It exits
+non-zero when the credential would be refused, so a runbook step can gate on it:
+
+```
+node dist/main.js doctor && <start the live session>
+```
+
+**The contract: a green `doctor` makes any later 401 vendor-side.** With `doctor` clean, a 401 means
+Hudu refused a well-shaped credential — a rotated, revoked, or role-restricted key — and the fix is
+at the vendor, not in the load recipe. Do not re-dial to test it: a 401 at the auth gate is the
+signal to stop and check, because repeated failures risk locking the account. Conversely, a 401
+whose envelope names a shape anomaly (`credentialShape: "anomalous"`) points back at the load.
+
+The server enforces the shape itself, so a bad load cannot reach the wire even if `doctor` is
+skipped: a malformed `HUDU_API_KEY` fails boot; a malformed `X-Hudu-Api-Key` header is refused
+before any client is built, with the typed `CREDENTIAL_MALFORMED` envelope (value-free, and
+`retryable: false`). Neither path dials.
+
+The server inspects **shape only** — length, a two-character prefix, and anomaly names. A credential
+value is never logged, never echoed in an error, and never returned by `/doctor`. The anomalies that
+fail a value are: preserved surrounding quotes (single or double), an embedded quote, a carriage
+return, a newline, edge whitespace, and a NUL byte.
 
 ## Configuration
 
@@ -143,7 +194,14 @@ credential. `asset_passwords.get` returns `password` and `otp_secret` as an ordi
 curated tools `hudu_find_asset_passwords_by_slug` and `hudu_get_password_folder` reach the same
 records. It is `deny` by default and refuses every operation on the `asset_passwords` and
 `password_folders` resources — through `hudu_read` and through those two tools alike, before any
-request is issued — so a deployment cannot hand a secret to a model by omission. It is scoped to the
+request is issued — so a deployment cannot hand a secret to a model by omission. The batch read
+`operations.fetchMany` (reachable through `hudu_read`) is refused the same way, per item: its
+operation key is not itself a credential read, so each item's resource is checked before any
+request, and a mixed batch is refused whole rather than partially dialed. The
+cross-resource resolve `operations.resolveAny` (also reachable through `hudu_read`) is gated the
+same way: under deny an explicitly named credential resource is refused, and an omitted resource
+list resolves to the permitted set, which excludes the credential resources from the fan-out. It
+is scoped to the
 whole resource rather than to the `expand` flag, because `asset_passwords.get` returns the secret
 without `expand`. It is independent of `HUDU_WRITE_POLICY`: `all` does not imply open secrets, and
 `allow` does not open writes. `hudu_search` is unaffected — it already redacts hits on those two
@@ -176,17 +234,97 @@ background, so a caller's later search is body-aware without the first one await
 walk (some clients enforce a 60s call timeout). Under `stdio` the one long-lived index stays warm and the
 default is `"index"`. Pass `tier:"index"` explicitly for a complete first answer.
 
+Three 0.12.0 preset knobs are env-tunable, each defaulting to the adopted behaviour.
+`HUDU_CACHE_PRESET` (`on` | `off`) toggles the read-through cache: the default `on` selects
+the SDK's `recommended` per-entity TTL preset, and `off` disables it, so repeated reads
+re-dial Hudu instead of being served from the cache.
+`HUDU_COOLDOWN` (`on` | `off`) is the 429 cooldown gate: `off` means a 429 retries per the
+agent profile instead of arming a local deadline whose refusals answer with `notSent: true`.
+`HUDU_TIMEOUT_MS` (positive integer milliseconds) is the whole-call deadline, default `30000`;
+it is always sent to the SDK explicitly, so it stays above the profile's 20 s.
+`blockPrivateHosts` deliberately gets no override: it is the literal-IP SSRF floor for
+caller-named origins — a security property, not a deployment preference.
+
+## SDK behaviour (0.12.0)
+
+Three SDK behaviours changed in the 0.12.0 line and shape a deployment:
+
+- **Redirects are refused, not followed.** Every Hudu request is sent with `redirect: 'manual'`;
+  a 3xx answer (any except 304) is a `REDIRECT_BLOCKED` error carrying the `location`, and the SDK
+  never follows it. If a reverse proxy in front of the Hudu origin answers 301/302 (scheme upgrade,
+  trailing slash, host rename), dial the final origin instead — the fix is topology, not config.
+- **Reads have a closed input contract.** `hudu_read` now refuses unknown input fields at the
+  schema layer with a typed `CONFIG_ERROR` naming the accepted fields, before any request;
+  `hudu_describe_operation` serves the same contract as `input_contract`. The batch read
+  `operations.fetchMany` (up to 20 single records across mixed resources in one call) is part of
+  the `hudu_read` surface; this server also registers the dedicated `hudu_fetch_many` tool from
+  the 0.12.0 CORE profile, with the secret-read policy applied to the batch's items on both
+  paths.
+- **Error envelopes carry the status in a field.** The error `message` is the vendor's short
+  detail (or a fixed default), never the status or the dialed host; those travel in their own
+  fields, and a long upstream body is still replaced by the response shape, not served. The
+  envelope also carries the SDK's `category`, `retryable`, `operation`, `suggestedAction`,
+  `fieldErrors` and `details` where the error has them, `notSent` on a locally issued 429
+  cooldown refusal, and `location` on a `REDIRECT_BLOCKED` refusal; the status field is
+  `httpStatus`. A 401/403-class credential refusal collapses to the fixed `UNAUTHORIZED`
+  envelope on every tool — the vendor's own message never crosses the boundary, and the
+  credential-shaped keys are redacted out of the payload the same way as the success path.
+  Two honest corners: `details` may carry the SDK's own 256-char vendor body snippet, labelled
+  untrusted like the rest of the envelope, and the `location` of a `REDIRECT_BLOCKED` refusal
+  is the vendor's own target, served so the deployment can report or verify it.
+
+Every client the server builds — the parent, the fail-closed placeholders and each
+(origin, credential) scope — opts into four 0.12.0 behaviours:
+
+- `profile: 'agent'`: the conservative agent preset for every option this server leaves unset
+  (1 retry, 240/min rate limit, concurrency 3, bounded resolution scans). The rate-limit bucket
+  is per client, i.e. per scope. The preset stays a deployment-wide constant with no env
+  override; the one deadline it would otherwise govern is pinned explicitly instead
+  (`HUDU_TIMEOUT_MS`, below), and the 429 now arms the cooldown gate instead of retrying
+  blindly.
+- `cache: 'recommended'` — env-toggled as `HUDU_CACHE_PRESET` (default `on`): the
+  per-entity read-through TTL preset (1 h structural / 5 min mutable / 1 min base). Caches are
+  per client, so per scope. A write through the write or delete client does not clear the read
+  client's cache (separate instances), so a read after a mutation is TTL-bounded stale, never
+  unbounded. `off` disables the read-through cache: repeated reads re-dial Hudu.
+- `blockPrivateHosts` on the per-scope clients: the literal-IP SSRF floor for CALLER-named
+  origins, fail-closed at client construction. It complements the `HUDU_ALLOWED_BASE_HOSTS`
+  hostname matcher (which alone can express wildcard suffixes) and holds even in
+  bring-your-own-origin mode, where that matcher is wide. The operator's own base — the
+  `HUDU_BASE_URL` under `stdio`, the default origin under `http` — is trusted at the process /
+  env boundary and is never floor-checked, so an on-prem install whose Hudu sits on a literal
+  private IP is unaffected by the upgrade. Deliberately no env override: it is a security
+  property, not a deployment preference.
+- `cooldown: { enabled: true }` — env-tunable as `HUDU_COOLDOWN` (default `on`): the 429
+  cooldown gate; a call refused locally by the gate answers with `notSent: true` in the error
+  envelope, so a model does not read a local refusal as a vendor rejection of a sent call.
+  `off` retries a 429 per the profile instead of arming a local deadline.
+
+The whole-call deadline is `HUDU_TIMEOUT_MS` (positive integer milliseconds, default `30000`):
+it is always passed to the SDK explicitly, so it stays above the agent profile's 20 s
+regardless of preset — the preset's 20 s would shorten a cold `tier:'index'` body-index walk
+that the 0.9.2 deployment tolerated at the SDK's 30 s, and a cold-scope search must not start
+timing out because of an upgrade.
+
+These are deployment-wide, not per-caller: `HUDU_CACHE_PRESET`, `HUDU_COOLDOWN` and
+`HUDU_TIMEOUT_MS` are env-tunable with the defaults above, while `profile` and
+`blockPrivateHosts` stay constants.
+
+
 ## Development
 
 ```
+git clone https://github.com/msoukhomlinov/iit-mcp-hudu.git
+cd iit-mcp-hudu
 npm install
+npm run build
 npm test
 npm run dev
 ```
 
 CI (`.github/workflows/ci.yml`) runs `typecheck`, `lint` and `test` on every push and pull request.
 
-`node-hudu` is pinned to `0.9.2`. The catalog hash test detects metadata drift; upgrades require
+`node-hudu` is pinned to `0.13.1`. The catalog hash test detects metadata drift; upgrades require
 review of the client authority, operation enums and redaction regressions. Docker uses `npm ci`.
 
 ## Deployment
@@ -195,6 +333,10 @@ review of the client authority, operation enums and redaction regressions. Docke
 not call Hudu — otherwise an upstream outage would cycle the container, turning a partial failure
 into a total one.
 
+`GET /doctor` (same trust model as `/healthz`: unauthenticated, answered before the MCP handler,
+zero Hudu requests) serves the same zero-wire credential-shape report the `doctor` subcommand
+prints, so a deployment can check its loaded credential without a vendor dial.
+
 The deployment definition is `docker-compose.yml`: its own Compose project, joining an existing
 `app_net` external network (create it with `docker network create app_net`, or rename it in the
 file). The listener is not published to the host, so put a TLS-terminating reverse proxy in front of

package/dist/config.d.ts

@@ -67,6 +67,15 @@ declare const schema: z.ZodObject<{
         warn: "warn";
         error: "error";
     }>>;
+    HUDU_CACHE_PRESET: z.ZodDefault<z.ZodEnum<{
+        on: "on";
+        off: "off";
+    }>>;
+    HUDU_COOLDOWN: z.ZodDefault<z.ZodEnum<{
+        on: "on";
+        off: "off";
+    }>>;
+    HUDU_TIMEOUT_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
 export type Config = z.infer<typeof schema>;
 /**

package/dist/config.js

@@ -9,6 +9,7 @@
 import * as z from 'zod';
 import { getCapability } from 'node-hudu/capabilities';
 import { SEARCH_RESOURCES } from 'node-hudu/mcp';
+import { CREDENTIAL_LOAD_HINT, detectCredentialShape } from './credential.js';
 import { isWriteEffect } from './policy.js';
 /**
  * `stdio` is the local path (Claude Code, Claude Desktop, VS Code): one process, one credential,
@@ -182,8 +183,41 @@ const schema = z
     HUDU_SECRET_READS: z.enum(SECRET_READ_POLICIES).default('deny'),
     PORT: z.coerce.number().int().positive().max(65535).default(8787),
     LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+    /**
+     * The read-through cache preset every client this server builds gets (SDK 0.12.0).
+     *
+     * The operator-facing toggle for the read-through cache. `on` (the default) selects the
+     * SDK's `recommended` per-entity TTL preset (1 h structural / 5 min mutable / 1 min base);
+     * `off` disables the read-through cache, so a repeated read re-dials Hudu instead of
+     * being served from the cache.
+     */
+    HUDU_CACHE_PRESET: z.enum(['on', 'off']).default('on'),
+    /**
+     * The 429 cooldown gate (SDK 0.12.0).
+     *
+     * `on` (the default) arms a local deadline after a vendor 429 whose retries are SPENT (the
+     * agent profile's 1 retry, so the first such call makes two wire attempts): calls the gate
+     * then refuses locally, and the error envelope marks them `notSent: true` so a local
+     * refusal stays distinguishable from a vendor rejection of a sent call. `off`
+     * retries a 429 per the profile's retry budget instead of arming a local deadline.
+     */
+    HUDU_COOLDOWN: z.enum(['on', 'off']).default('on'),
+    /**
+     * The whole-call deadline in milliseconds (SDK 0.12.0). Positive integer.
+     *
+     * Defaults to 30000 and is always passed to the SDK explicitly, so it wins over the
+     * agent profile's 20 s deadline regardless of preset; the default keeps the tolerance
+     * a cold `tier:'index'` body-index walk had before the 0.12.0 adoption.
+     */
+    HUDU_TIMEOUT_MS: z.coerce.number().int().positive().default(30000),
 })
     .superRefine((c, ctx) => {
+    // Pre-dial integrity check (2026-10-07 Autotask incident class): a credential whose bytes were
+    // mangled by a quote-preserving load is refused HERE, before any client is constructed and so
+    // before the first dial. Refusal is transport-independent: `HUDU_API_KEY` under `http` is the
+    // default key for a request that brings none, and presenting a mangled one is the same
+    // incident on a different path.
+    checkCredentialShape(c.HUDU_API_KEY, ctx, 'HUDU_API_KEY');
     // `stdio` has exactly one origin and one credential (the environment's), so it requires both.
     // Under `http` both are optional defaults: a caller's `x-hudu-*` headers win, and the defaults
     // fill in whatever a request leaves out (see `resolveHuduClient` for how they pair).
@@ -300,6 +334,34 @@ const schema = z
         }
     }
 });
+/**
+ * Apply the same check to `HUDU_API_KEY` here as to the per-request key under `http`.
+ *
+ * {@link CREDENTIAL_LOAD_HINT} — the env-load pitfall the refusal ends with — lives in
+ * `src/credential.ts` beside the anomaly vocabulary, so the boot error and the http refusal explain
+ * the same cause in the same words.
+ *
+ * Lives in a refinement rather than in the field's own `preprocess` so the issue carries the same
+ * `path` (the variable name) the operator already reads, and so a value that is BOTH blank and
+ * malformed reports only the blank case.
+ *
+ * The message never contains a character of the value: the anomaly names and the length are the
+ * whole diagnostic. That matters — the value is the secret, and this text is printed to the boot
+ * log (and, under `http`, would be too).
+ */
+function checkCredentialShape(value, ctx, path) {
+    if (value === undefined)
+        return;
+    const anomalies = detectCredentialShape(value);
+    if (anomalies.length === 0)
+        return;
+    ctx.addIssue({
+        code: 'custom',
+        path: [path],
+        message: `${path} has a value whose shape cannot be right (length ${value.length}, ${anomalies.join(', ')}); ` +
+            `the server refuses to boot rather than present a malformed credential to Hudu. ${CREDENTIAL_LOAD_HINT}`,
+    });
+}
 /**
  * Parse and validate configuration from an environment-shaped record.
  *

package/dist/credential.d.ts

@@ -0,0 +1,67 @@
+/**
+ * credential.ts — the pre-dispatch shape gate for Hudu credential values, and the value-free
+ * description of a credential the operator-facing doctor reports.
+ *
+ * Why this exists (2026-10-07 Autotask incident): a `.env` value written `HUDU_API_KEY='a$b'` was
+ * fed through a quote-preserving dotenv parser, so the quotes reached the wire as part of the
+ * secret. The vendor answered 401 and the operator read three opaque failures as a rotated key —
+ * on an account where retries risk a lock. Nothing in this package, and nothing in node-hudu
+ * 0.12.0, inspects the shape of a credential value before it is dialed, so that class of misload
+ * booted cleanly and dialed.
+ *
+ * This module closes that at the boundary. It never inspects, stores or reports a credential
+ * VALUE — only shape facts derived from it (a length, a two-character prefix, and which anomaly
+ * was seen). {@link describeCredential} and {@link detectCredentialShape} return metadata for a
+ * value caller; no field of either ever carries a character of the value itself, so both are safe
+ * to log and to serialize.
+ */
+export declare const CREDENTIAL_LOAD_HINT = "load the value the way the file documents: values written in single quotes (the .env.example style) are only unquoted by shell sourcing \u2014 `set -a; . ./.env; set +a` \u2014 and a quote-preserving parser such as a plain dotenv parse of the file feeds the quotes to the vendor; run `doctor` to confirm the shape";
+/**
+ * The shape anomalies a mislanded credential file load produces, in the order they are reported.
+ *
+ * `surrounding_single_quotes` is the incident itself: a value written `KEY='a$b'` in a `.env` loses
+ * its quotes when the file is SOURCED by a shell, so a value that still carries them here was never
+ * shell-sourced (or was parsed by something that preserves them).
+ */
+export declare const CREDENTIAL_ANOMALIES: readonly ["surrounding_double_quotes", "surrounding_single_quotes", "embedded_quotes", "carriage_return", "newline", "edge_whitespace", "nul_byte"];
+export type CredentialAnomaly = (typeof CREDENTIAL_ANOMALIES)[number];
+/**
+ * Whether a shape anomaly means the server must refuse to dial rather than warn.
+ *
+ * Every anomaly in {@link CREDENTIAL_ANOMALIES} changes the bytes presented to the vendor, so
+ * every one of them is refused by both intake paths. The predicate is a function, not a literal
+ * `true` in the callers, so the decision lives in one place if it ever narrows.
+ */
+export declare function isFatalAnomaly(anomaly: CredentialAnomaly): boolean;
+/** The value-free shape description of one credential-shaped string. */
+export interface CredentialShape {
+    /** Character count of the value as received. A count, never a character of the value. */
+    readonly length: number;
+    /**
+     * The first two characters, which identify the format for the operator (a Hudu API key starts
+     * `ey` — a base64url-encoded JWT). Two characters of an already-leaked-format credential say
+     * nothing; the other 500 do.
+     */
+    readonly prefix2: string;
+    /** Every anomaly seen, in {@link CREDENTIAL_ANOMALIES} order. */
+    readonly anomalies: readonly CredentialAnomaly[];
+}
+/** Every anomaly present in `value`, in a fixed order. Never returns any part of the value. */
+export declare function detectCredentialShape(value: string): readonly CredentialAnomaly[];
+/**
+ * The shape facts an operator-facing surface may report for one credential field.
+ *
+ * `prefix2` is emitted for values of at least two characters and a single `<1>` otherwise, so the
+ * report never implies a one-character secret. The value itself is never returned.
+ */
+export declare function describeCredential(value: string | undefined): CredentialShape | undefined;
+/**
+ * The partial config one credential-bearing attempt produced, in the shape the operator's next
+ * step needs: whether the variable was set at all, and its value-free shape when it was.
+ */
+export interface CredentialReport {
+    readonly present: boolean;
+    readonly shape?: CredentialShape;
+}
+/** Describe one credential-bearing variable for a diagnostic surface. Never carries its value. */
+export declare function reportCredential(env: Record<string, string | undefined>, name: string): CredentialReport;

package/dist/credential.js

@@ -0,0 +1,101 @@
+/**
+ * credential.ts — the pre-dispatch shape gate for Hudu credential values, and the value-free
+ * description of a credential the operator-facing doctor reports.
+ *
+ * Why this exists (2026-10-07 Autotask incident): a `.env` value written `HUDU_API_KEY='a$b'` was
+ * fed through a quote-preserving dotenv parser, so the quotes reached the wire as part of the
+ * secret. The vendor answered 401 and the operator read three opaque failures as a rotated key —
+ * on an account where retries risk a lock. Nothing in this package, and nothing in node-hudu
+ * 0.12.0, inspects the shape of a credential value before it is dialed, so that class of misload
+ * booted cleanly and dialed.
+ *
+ * This module closes that at the boundary. It never inspects, stores or reports a credential
+ * VALUE — only shape facts derived from it (a length, a two-character prefix, and which anomaly
+ * was seen). {@link describeCredential} and {@link detectCredentialShape} return metadata for a
+ * value caller; no field of either ever carries a character of the value itself, so both are safe
+ * to log and to serialize.
+ */
+export const CREDENTIAL_LOAD_HINT = 'load the value the way the file documents: values written in single quotes (the .env.example style) are only unquoted by shell sourcing — `set -a; . ./.env; set +a` — and a quote-preserving parser such as a plain dotenv parse of the file feeds the quotes to the vendor; run `doctor` to confirm the shape';
+/**
+ * The shape anomalies a mislanded credential file load produces, in the order they are reported.
+ *
+ * `surrounding_single_quotes` is the incident itself: a value written `KEY='a$b'` in a `.env` loses
+ * its quotes when the file is SOURCED by a shell, so a value that still carries them here was never
+ * shell-sourced (or was parsed by something that preserves them).
+ */
+export const CREDENTIAL_ANOMALIES = [
+    'surrounding_double_quotes',
+    'surrounding_single_quotes',
+    'embedded_quotes',
+    'carriage_return',
+    'newline',
+    'edge_whitespace',
+    'nul_byte',
+];
+/**
+ * Whether a shape anomaly means the server must refuse to dial rather than warn.
+ *
+ * Every anomaly in {@link CREDENTIAL_ANOMALIES} changes the bytes presented to the vendor, so
+ * every one of them is refused by both intake paths. The predicate is a function, not a literal
+ * `true` in the callers, so the decision lives in one place if it ever narrows.
+ */
+export function isFatalAnomaly(anomaly) {
+    return CREDENTIAL_ANOMALIES.includes(anomaly);
+}
+/** Every anomaly present in `value`, in a fixed order. Never returns any part of the value. */
+export function detectCredentialShape(value) {
+    const anomalies = [];
+    // The incident, first: quotes preserved by a parser that should have consumed them.
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"'))
+        anomalies.push('surrounding_double_quotes');
+    if (value.length >= 2 && value.startsWith("'") && value.endsWith("'"))
+        anomalies.push('surrounding_single_quotes');
+    // A quote that survived inside the value: a shell-sourced value cannot contain a bare one, and
+    // a shell that never ran leaves them where a parser put them.
+    if (value.includes('"') || value.includes("'"))
+        anomalies.push('embedded_quotes');
+    // CRLF is the canonical Windows-edited .env contamination: the CRLF and everything after it
+    // reaches the vendor as part of the secret. (A per-request header cannot carry one — Node's
+    // `Headers` strips it — so this branch is reachable only through the server-held value.)
+    if (value.includes('\r'))
+        anomalies.push('carriage_return');
+    if (value.includes('\n'))
+        anomalies.push('newline');
+    // A trailing space from `KEY=value ` is invisible in every editor and is presented verbatim.
+    // `trim()` also catches a tab, which survives a header hop even though Node's Headers strips
+    // space at the edges of a header value.
+    if (value.length > 0 && value !== value.trim())
+        anomalies.push('edge_whitespace');
+    // NUL is not a legal header character: Node's `Headers.set` THROWS on a value carrying one, and
+    // that throw happens before any auth strategy runs, so a request with such a key answers with a
+    // framework error instead of a typed refusal. Flagged here so the server-held value is refused at
+    // boot, where the operator can act on it.
+    if (value.includes('\u0000'))
+        anomalies.push('nul_byte');
+    return anomalies;
+}
+/**
+ * The shape facts an operator-facing surface may report for one credential field.
+ *
+ * `prefix2` is emitted for values of at least two characters and a single `<1>` otherwise, so the
+ * report never implies a one-character secret. The value itself is never returned.
+ */
+export function describeCredential(value) {
+    if (value === undefined)
+        return undefined;
+    return {
+        length: value.length,
+        prefix2: value.length >= 2 ? value.slice(0, 2) : '<1>',
+        anomalies: detectCredentialShape(value),
+    };
+}
+/** Describe one credential-bearing variable for a diagnostic surface. Never carries its value. */
+export function reportCredential(env, name) {
+    const raw = env[name];
+    // `''` is the .env.example placeholder an operator forgot to fill in: "not set", exactly as the
+    // boot schema normalises it, rather than a zero-length credential.
+    if (raw === undefined || raw.trim() === '')
+        return { present: false };
+    return { present: true, shape: describeCredential(raw) };
+}
+//# sourceMappingURL=credential.js.map

package/dist/doctor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * doctor.ts — the zero-wire credential/config preflight.
+ *
+ * The problem it solves is the expensive one: today the only way to confirm that a credential
+ * loaded intact is to dial Hudu, and against a vendor account where repeated auth failures risk a
+ * lock (2026-10-07 Autotask incident) that confirmation is the most expensive call the deployment
+ * can make. `doctor` answers the same question — "is the value I loaded shaped like the credential
+ * the vendor issued, and is it aimed at the origin I meant?" — from the process's own environment,
+ * with ZERO vendor requests, by construction: this module imports no Hudu client and reads no
+ * network, so there is nothing it could dial even if a value invited it.
+ *
+ * It reports shape, never value: a length, a two-character prefix and which anomalies were seen.
+ * The contract it feeds (README / `.env.example`): run `doctor` before a live session — a green
+ * doctor means any later 401 is vendor-side (rotated, revoked or role-restricted key), not a
+ * mangled load.
+ */
+import type { Config } from './config.js';
+/** How one credential field's shape check came out. */
+export type DoctorCheckStatus = 'absent' | 'ok' | 'malformed';
+/** The shape report for one credential-bearing variable: metadata only, never a value. */
+export interface DoctorCredentialCheck {
+    readonly name: string;
+    readonly status: DoctorCheckStatus;
+    readonly length?: number;
+    readonly prefix2?: string;
+    readonly shapeOk?: boolean;
+    readonly anomalies?: readonly string[];
+    /**
+     * Whether the intake path this variable feeds would refuse it. Under `stdio` `HUDU_API_KEY` is
+     * required, so an absent one is as fatal as a malformed one; under `http` it is an optional
+     * default and absence is fine.
+     */
+    readonly blocks?: boolean;
+}
+/** The shape report for one origin value: host and scheme only, never a path or a query. */
+export interface DoctorBaseCheck {
+    readonly name: string;
+    readonly present: boolean;
+    /** `origin` (scheme + host + port), never the full URL. The origin is what the SDK dials. */
+    readonly origin?: string;
+    readonly resolvable: boolean;
+}
+/** The whole zero-wire report. `ok: false` means at least one field would be refused. */
+export interface DoctorReport {
+    readonly ok: boolean;
+    readonly transport: Config['MCP_TRANSPORT'];
+    readonly dialed: number;
+    readonly credentials: readonly DoctorCredentialCheck[];
+    readonly bases: readonly DoctorBaseCheck[];
+    readonly notes: readonly string[];
+}
+/**
+ * Build the doctor report for an already-validated config.
+ *
+ * Takes the parsed `Config` rather than a raw environment on purpose: `loadConfig` has already
+ * refused a blank/missing/origin-invalid configuration — and, at boot, a malformed credential — so
+ * reaching here means every structural question is settled and only the SHAPE facts remain.
+ *
+ * A malformed credential therefore normally reaches the operator as the boot refusal (the CLI
+ * prints it verbatim, exit 1, and it names the anomaly and the load recipe). This report is the
+ * same facts in structured form, for a config that is already shaped like a working one; the two
+ * routes are tested together in `test/doctor.test.ts`.
+ */
+export declare function runDoctor(config: Config): DoctorReport;