iit-mcp-hudu 0.2.0 → 0.2.3

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
@@ -32,13 +58,26 @@ MCP_TRANSPORT=stdio
 # HUDU_ALLOW_ANY_BASE_HOST=false
 
 # Omit mutation tools entirely by default. Set false before enabling a write policy.
+#
+# Deployment spectrum — the variables below compose it, and every step stays fail-closed:
+#   light read-only : the shipped defaults (HUDU_READ_ONLY=true, HUDU_WRITE_POLICY=deny,
+#                    HUDU_SECRET_READS=deny). Reads only; no mutation tools at all.
+#   scoped writes   : HUDU_READ_ONLY=false, HUDU_WRITE_POLICY=allow_list,
+#                    HUDU_WRITE_ALLOW=<operation keys> (plus HUDU_SECRET_READS=allow if
+#                    plaintext credential reads are wanted).
+#   full read-write : HUDU_READ_ONLY=false, HUDU_WRITE_POLICY=all (plus HUDU_SECRET_READS=allow).
+#                    Every write and destructive operation is permitted; the SDK's per-mode
+#                    client gates (read / write / destructive) still apply underneath.
 HUDU_READ_ONLY=true
+# HUDU_READ_ONLY=false
 
 # Authority over the mutation dispatchers. deny (the default) refuses every write and destructive
 # operation; allow_list permits only the keys in HUDU_WRITE_ALLOW; all is today's behaviour and has
 # to be typed out deliberately. An unset value means deny, so forgetting this gets a read-only
 # server, never an open one. Reads are never affected.
 HUDU_WRITE_POLICY=deny
+# HUDU_WRITE_POLICY=allow_list
+# HUDU_WRITE_POLICY=all
 
 # Authority over reads that return a plaintext credential -- independent of HUDU_WRITE_POLICY, which
 # never covers them: asset_passwords.get returns password and otp_secret as an ordinary read. deny
@@ -47,10 +86,16 @@ HUDU_WRITE_POLICY=deny
 # resource, not to the expand flag, because the secret comes back without expand. hudu_search is
 # unaffected; it redacts those resources already.
 HUDU_SECRET_READS=deny
+# HUDU_SECRET_READS=allow    # permits plaintext credential reads; SDK search results stay redacted
 
 # Only read under HUDU_WRITE_POLICY=allow_list. Comma-separated registry operation keys, e.g.
 # articles.update,assets.create. It must be non-empty and every key must exist in the registry (and
 # be a write) or the container fails at boot with the variable named. Ignored under deny/all.
+# The write client is offered the write-effect keys and the delete client the destructive-effect
+# keys from this one list: to reach the same coverage as `all` via an allow list, it must name
+# every write and every destructive operation (the full key set is the node-hudu capability
+# registry, published in MCP_TOOL_MANIFEST.md). The two-key line below is the minimal shape, not
+# full coverage.
 # HUDU_WRITE_ALLOW=articles.update,assets.create
 
 PORT=8787
@@ -96,4 +141,3 @@ HUDU_SEARCH_MAX_INDEX_PAGES=40
 # Leave it out of .env — the deploy script exports it.
 # HUDU_IMAGE_TAG=
 
-# HUDU_SECRET_READS=allow permits resource access; SDK results remain redacted.

package/README.md

@@ -25,7 +25,7 @@ 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 the node-hudu 0.12.0 line; 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.
+These tools run on node-hudu 0.13.2; 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
@@ -76,6 +76,62 @@ or in `.mcp.json` / Claude Desktop config:
 **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.**
+
+```
+set -a; . ./.env; set +a      # the .env.example recipe, for a file of single-quoted values
+```
+
+`.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. Since node-hudu 0.13.2 the SDK enforces credential shape
+itself too — refusing a contaminated value at client construction and attaching a value-free shape
+diagnostic to a refused credential — and this server consumes that diagnostic directly on a 401;
+the server's own gate stays as the boundary guard, a superset of the SDK's checks.
+
+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, an embedded control character (any non-printable ASCII byte besides those),
+edge whitespace, and a NUL byte.
+
 ## Configuration
 
 Copy `.env.example`. Every variable is validated at boot; the process exits non-zero on an invalid
@@ -272,7 +328,7 @@ 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.12.0`. The catalog hash test detects metadata drift; upgrades require
+`node-hudu` is pinned to `0.13.2`. The catalog hash test detects metadata drift; upgrades require
 review of the client authority, operation enums and redaction regressions. Docker uses `npm ci`.
 
 ## Deployment
@@ -281,6 +337,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.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,
@@ -211,6 +212,12 @@ const schema = z
     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).
@@ -327,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", "embedded_control_character", "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,115 @@
+/**
+ * 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',
+    'embedded_control_character',
+    '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');
+    // Any other non-printable ASCII byte (a tab, bell or stray escape; NUL is named separately
+    // below): a Hudu API key is base64url and cannot legally carry one, so any of them means the
+    // load mangled the value.
+    let embeddedControl = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if ((code < 0x20 && code !== 0x0d && code !== 0x0a) || code === 0x7f) {
+            embeddedControl = true;
+            break;
+        }
+    }
+    if (embeddedControl)
+        anomalies.push('embedded_control_character');
+    // 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;

package/dist/doctor.js

@@ -0,0 +1,79 @@
+import { describeCredential } from './credential.js';
+/** Check one credential-shaped value without ever carrying it out of this function. */
+function credentialCheck(name, value, required) {
+    if (value === undefined || value.trim() === '') {
+        // "not set", never "length 0": the boot schema normalises a blank the same way, and a blank is
+        // the `.env.example` placeholder rather than a credential the vendor would see.
+        return { name, status: 'absent', blocks: required };
+    }
+    const shape = describeCredential(value);
+    const malformed = shape.anomalies.length > 0;
+    return {
+        name,
+        status: malformed ? 'malformed' : 'ok',
+        length: shape.length,
+        prefix2: shape.prefix2,
+        shapeOk: !malformed,
+        anomalies: shape.anomalies,
+        // `blocks` is "this field would be refused", and only a malformed or an absent-and-required
+        // field is. A present, well-shaped value never blocks, however much the deployment needs it.
+        blocks: malformed,
+    };
+}
+/**
+ * Check one origin value: does it parse, and what origin will actually be dialed?
+ *
+ * An origin is not a secret (the operator wrote it), but only its origin crosses into the report:
+ * a URL with userinfo (`https://user:pass@host`) would otherwise carry a credential into every log
+ * sink this report reaches, so the origin is derived and the raw value is dropped.
+ */
+function baseCheck(name, value) {
+    if (value === undefined || value.trim() === '')
+        return { name, present: false, resolvable: false };
+    try {
+        return { name, present: true, origin: new URL(value).origin, resolvable: true };
+    }
+    catch {
+        return { name, present: true, resolvable: false };
+    }
+}
+/**
+ * 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 function runDoctor(config) {
+    const isStdio = config.MCP_TRANSPORT === 'stdio';
+    // The environment is exactly one credential path; the per-request header is not reachable from a
+    // preflight (nothing is serving yet), and saying so is part of the contract.
+    const credentials = [
+        credentialCheck('HUDU_API_KEY', config.HUDU_API_KEY, isStdio),
+    ];
+    const bases = [baseCheck('HUDU_BASE_URL', config.HUDU_BASE_URL)];
+    const notes = [
+        'zero vendor requests: this report is computed from the environment alone',
+        'shape facts only (length, two-character prefix, anomaly names) — a credential value is never read out',
+    ];
+    if (!isStdio) {
+        notes.push('http transport: the tool-call credential arrives per request in x-hudu-api-key and is checked at that boundary, not here');
+    }
+    if (credentials.some((c) => c.blocks)) {
+        notes.push('a credential-bearing variable would be refused by the server: fix the load recipe before any live session (a 401 costs a real vendor auth failure, and repeated ones risk an account lock)');
+    }
+    return {
+        ok: !credentials.some((c) => c.blocks) && bases.every((b) => !b.present || b.resolvable),
+        transport: config.MCP_TRANSPORT,
+        dialed: 0,
+        credentials,
+        bases,
+        notes,
+    };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/http.d.ts

@@ -16,6 +16,7 @@
 import { type IncomingMessage, type ServerResponse, type Server } from 'node:http';
 import type { Config } from './config.js';
 import type { Logger } from './logger.js';
+import { type DoctorReport } from './doctor.js';
 /** A fetch-shaped MCP handler, as returned by the SDK's `createMcpHandler`. */
 export interface FetchHandler {
     fetch(request: Request): Promise<Response>;
@@ -23,11 +24,25 @@ export interface FetchHandler {
 /** Liveness path. Answered before authentication so a container healthcheck needs no credential. */
 export declare const HEALTH_PATH = "/healthz";
 /**
- * Build the fetch-level request handler: health, then MCP.
+ * The zero-wire credential preflight route.
+ *
+ * Same trust model as {@link HEALTH_PATH}: answered before the MCP handler, never authenticated,
+ * and never touching Hudu. It reports the shape of the SERVER-HELD credential only — the caller's
+ * own per-request key is checked at the tool boundary, one request at a time, and is deliberately
+ * not echoed back to the caller that sent it. Reporting shape facts (a length, a two-character
+ * prefix, anomaly names) about the server's own environment is therefore not a disclosure: the
+ * caller that can reach this listener is the operator who set that environment.
+ */
+export declare const DOCTOR_PATH = "/doctor";
+/**
+ * Build the fetch-level request handler: health, doctor, then MCP.
  *
  * Split out from the listener so the request path is testable without binding a port.
+ *
+ * `doctor` is a builder, not a constant, so the route reports THIS process's parsed config and so
+ * the route itself stays Hudu-free: nothing is read until a request arrives.
  */
-export declare function createFetchHandler(mcp: FetchHandler): (request: Request) => Promise<Response>;
+export declare function createFetchHandler(mcp: FetchHandler, doctor?: () => DoctorReport): (request: Request) => Promise<Response>;
 /** Node has no fetch-shaped HTTP server; this is the smallest bridge to one. */
 export declare function toWebRequest(req: IncomingMessage, port: number): Promise<Request>;
 /**

package/dist/http.js

@@ -17,22 +17,42 @@ import { createServer } from 'node:http';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { HUDU_BASE_URL_HEADER, HUDU_KEY_HEADER } from './auth.js';
+import { runDoctor } from './doctor.js';
 /** The headers that carry per-request scope, and so must never be read from a duplicated pair. */
 const CREDENTIAL_HEADERS = new Set([HUDU_KEY_HEADER, HUDU_BASE_URL_HEADER]);
 /** Liveness path. Answered before authentication so a container healthcheck needs no credential. */
 export const HEALTH_PATH = '/healthz';
 /**
- * Build the fetch-level request handler: health, then MCP.
+ * The zero-wire credential preflight route.
+ *
+ * Same trust model as {@link HEALTH_PATH}: answered before the MCP handler, never authenticated,
+ * and never touching Hudu. It reports the shape of the SERVER-HELD credential only — the caller's
+ * own per-request key is checked at the tool boundary, one request at a time, and is deliberately
+ * not echoed back to the caller that sent it. Reporting shape facts (a length, a two-character
+ * prefix, anomaly names) about the server's own environment is therefore not a disclosure: the
+ * caller that can reach this listener is the operator who set that environment.
+ */
+export const DOCTOR_PATH = '/doctor';
+/**
+ * Build the fetch-level request handler: health, doctor, then MCP.
  *
  * Split out from the listener so the request path is testable without binding a port.
+ *
+ * `doctor` is a builder, not a constant, so the route reports THIS process's parsed config and so
+ * the route itself stays Hudu-free: nothing is read until a request arrives.
  */
-export function createFetchHandler(mcp) {
+export function createFetchHandler(mcp, doctor) {
     return async function handle(request) {
         const url = new URL(request.url);
         // Liveness only. It must not touch Hudu — see the Dockerfile HEALTHCHECK note.
         if (url.pathname === HEALTH_PATH) {
             return Response.json({ status: 'ok' });
         }
+        // Credential shape, still no Hudu. `dialed: 0` is a property of the implementation (see
+        // `src/doctor.ts`, which holds no client), not a counter that a bug could leave at zero.
+        if (url.pathname === DOCTOR_PATH && doctor !== undefined) {
+            return Response.json(doctor());
+        }
         // No check for the Hudu key: a request with no key is let through so the SDK can answer
         // `initialize`/`tools/list`, which never reach Hudu and which clients need to sync the tool
         // catalog. The per-request factory resolves such a request to a client that holds no credential
@@ -98,7 +118,7 @@ export async function send(res, response) {
  * `exit` is a parameter only so a test can watch a listen failure without killing the test runner.
  */
 export function startHttpServer(config, mcp, log, exit = process.exit) {
-    const handle = createFetchHandler(mcp);
+    const handle = createFetchHandler(mcp, () => runDoctor(config));
     const server = createServer((req, res) => {
         void toWebRequest(req, config.PORT)
             .then(handle)