iit-mcp-hudu 0.1.0

package/.env.example

@@ -0,0 +1,81 @@
+# The Hudu origin the server talks to -- REQUIRED for stdio, an optional default for http.
+#
+# stdio: the process IS the trust boundary, so the origin comes from the environment.
+# http:  callers normally name their own origin per request in the X-Hudu-Base-Url header. When set,
+#        this is the origin used by a request that sends no such header. The default key below is
+#        only ever presented to this origin.
+# HUDU_BASE_URL=https://hudu.example.com
+
+# stdio (local: Claude Code, Claude Desktop, VS Code) or http (remote MCP clients).
+MCP_TRANSPORT=stdio
+
+# The server-held Hudu credential -- REQUIRED for stdio, an optional default for http.
+#
+# stdio: the process IS the trust boundary, so the key comes from the environment.
+# http:  the key normally arrives per request in the X-Hudu-Api-Key header (a client can scope it
+#        per user or per agent, so each caller reaches Hudu as itself). When set here, every request
+#        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.
+# HUDU_API_KEY=
+
+# http only, optional. Hosts a caller may name in X-Hudu-Base-Url: comma-separated exact hostnames or
+# *.example.com subdomain suffixes (no scheme, port or path). Unset alongside a set HUDU_BASE_URL,
+# only that default origin is accepted. Unset with no HUDU_BASE_URL, any caller-named origin would be
+# accepted, so whoever can reach the listener could make the server dial hosts of their choosing:
+# the server refuses to boot in that case unless HUDU_ALLOW_ANY_BASE_HOST=true. An explicit list
+# never checks HUDU_BASE_URL against it.
+# HUDU_ALLOWED_BASE_HOSTS=hudu.example.com,*.corp.example.com
+
+# http only. Boot without an allow-list and accept any origin a caller names. Use only when every
+# caller that can reach the listener is trusted.
+# HUDU_ALLOW_ANY_BASE_HOST=false
+
+# Omit mutation tools entirely by default. Set false before enabling a write policy.
+HUDU_READ_ONLY=true
+
+# 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
+
+# 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
+# (the default) refuses every asset_passwords.* and password_folders.* operation, through the dispatchers
+# and through hudu_find_asset_passwords_by_slug / hudu_get_password_folder alike. Scoped to the whole
+# 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
+
+# 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.
+# HUDU_WRITE_ALLOW=articles.update,assets.create
+
+PORT=8787
+LOG_LEVEL=info
+
+# Pages the search body index walks per resource (SDK default 250 = 25,000 records). Lower it when
+# the tenant's assets are numerous enough to evict article bodies from the 64 MB text budget: the
+# article walk must fit with room to spare or every search answers body-blind. 40 covers ~4,000
+# articles and caps assets at ~4,000.
+HUDU_SEARCH_MAX_INDEX_PAGES=40
+
+# 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
+# advertises a guaranteed-empty read nor leaks an authorization failure for a resource the key
+# cannot reach. A Hudu API key inherits its user's role, so a "Reader" key may read fewer than all
+# eight. Comma-separated, each name validated against the SDK's searchable set at boot. Applies to
+# the cross-resource reads (hudu_search, hudu_resolve_any) and the same operations through
+# hudu_read; the dedicated per-resource resolve tools are unaffected.
+# HUDU_SEARCH_RESOURCES=articles,assets,companies,users,groups,websites
+
+# Image tag docker-compose.yml builds and runs as. scripts/deploy.sh sets it to the git short SHA
+# of the deployed commit, so the running container is always tied to a commit and the previous
+# tag stays resolvable for rollback. Do not deploy by hand with it unset, and never tag :latest.
+# 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Soukhomlinov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# iit-mcp-hudu
+
+MCP server for Hudu IT documentation, built on the [`node-hudu`](https://www.npmjs.com/package/node-hudu) SDK.
+
+## 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,
+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.
+
+The four list tools each wrap exactly ONE fixed registry operation (`companies.list` /
+`articles.list` / `assets.listAcrossCompanies` / `asset_layouts.list`), take exactly one page and
+accept no operation selector or nested invocation, so an ungated Reader can page companies,
+articles, assets or asset layouts without using a registry dispatcher and without exposing the write
+surface. The first three take `page` / `page_size` (capped at 100); `hudu_list_asset_layouts` takes
+`page` only, because `/asset_layouts` ignores `page_size` — a caller bound would truncate a vendor
+page and skip rows as `page` advanced, so the tool returns the vendor page whole and page N is
+always the vendor's Nth page. For the searchable resources (`companies` / `articles` /
+`assets`) a resource excluded by `HUDU_SEARCH_RESOURCES` is refused by the list tool too, before any
+request; `asset_layouts` is not searchable (the SDK declares no vendor text filter for it), so
+`hudu_list_asset_layouts` follows the same reachability as the existing ungated
+`hudu_get_asset_layout` tool.
+
+## Transports
+
+| Transport | For | Caller auth | Hudu credential |
+|---|---|---|---|
+| `stdio` | Claude Code, Claude Desktop, VS Code | none — the process boundary is the trust boundary | `HUDU_API_KEY` + `HUDU_BASE_URL` env |
+| `http` | Remote MCP clients | none — private, unpublished network | per request: `X-Hudu-Api-Key` + `X-Hudu-Base-Url` headers, or the optional `HUDU_API_KEY` + `HUDU_BASE_URL` defaults |
+
+## Local use (stdio)
+
+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:
+
+```
+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
+```
+
+or in `.mcp.json` / Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "hudu": {
+      "command": "node",
+      "args": ["/absolute/path/to/iit-mcp-hudu/dist/main.js"],
+      "env": { "HUDU_API_KEY": "your-key", "HUDU_BASE_URL": "https://your.hudu.host" }
+    }
+  }
+}
+```
+
+**From npm:**
+
+```
+claude mcp add hudu \
+  --env HUDU_API_KEY=your-key --env HUDU_BASE_URL=https://your.hudu.host \
+  -- npx -y iit-mcp-hudu
+```
+
+or `"command": "npx", "args": ["-y", "iit-mcp-hudu"]` in the JSON config above.
+
+## Configuration
+
+Copy `.env.example`. Every variable is validated at boot; the process exits non-zero on an invalid
+config rather than failing at the first tool call.
+
+Under `http` the caller normally supplies both per request: its own Hudu API key in `X-Hudu-Api-Key`
+and the origin that key belongs to in `X-Hudu-Base-Url` (an absolute `http`/`https` origin, no
+path — validated by the SDK when the scoped client is built). A client can scope the key
+per user or per agent to match how the connection is configured, so a caller can read exactly
+what its own Hudu role permits and no more. There is no shared token: the listener is
+unauthenticated and must stay on a private, unpublished network.
+
+Both may instead be set as **defaults**. `HUDU_BASE_URL` and `HUDU_API_KEY` are required under
+`stdio` and optional under `http`, where a request's headers win and the defaults fill in whatever
+it omits. Setting `HUDU_API_KEY` under `http` means every request without its own key runs as that
+key, so set it only when that is intended: with no shared token, the private network is the only
+gate on who can use it. It is only ever presented to the default
+`HUDU_BASE_URL`: a request that names some other origin and brings no key of its own gets no
+credential and fails closed, so a caller cannot aim the server's key at a host it controls. (A
+blank value, as a copied `.env.example` leaves it, is treated as unset.) Each (origin, credential)
+pair gets its own scoped client (its own search index) cached by the pair's hash and capped, so
+one caller's indexed article bodies can never answer another's search.
+
+`HUDU_ALLOWED_BASE_HOSTS` (`http` only; required unless `HUDU_ALLOW_ANY_BASE_HOST=true`) restricts which origins a caller may name in
+`X-Hudu-Base-Url`: a comma-separated list of exact hostnames or `*.example.com` subdomain suffixes
+(no scheme, port or path; write an internationalised name in punycode). When it is unset and
+`HUDU_BASE_URL` is set, only that default origin is accepted. When both are unset, any caller-named
+origin would be accepted, so anyone who can reach the listener could make the server send requests
+(carrying their key) to hosts of their choosing; the server refuses to boot in that case unless
+`HUDU_ALLOW_ANY_BASE_HOST=true` opts in, for a listener only trusted callers can reach. The check is
+on the hostname string: it does not resolve DNS or block private addresses, so do not list a name you
+do not control. A request naming a host outside the effective policy fails closed on every tool call
+without dialing it. Only the hostname is checked for an explicit list: an allowed host is accepted on
+any port and over `http`. The default `HUDU_BASE_URL` is never checked against an explicit list.
+
+With no usable key (none in the header and no `HUDU_API_KEY` default) a request is still let
+through: `initialize` and `tools/list` never reach Hudu, and a client's catalog sync needs them. Such
+a request resolves to a credential-less client that throws before any Hudu request is built, so
+every tool call fails closed rather than borrowing an identity. A request that has a key but no
+origin (no header and no `HUDU_BASE_URL` default) is let through the same way and fails closed on
+every tool call, with the error naming the missing header. A
+credential header sent twice (which Node would otherwise join with `", "`) is treated as absent
+for the same reason.
+
+`HUDU_READ_ONLY=true` is the default and omits both mutation tools entirely, regardless of
+write policy. To enable mutations, explicitly set it to `false` and configure
+`HUDU_WRITE_POLICY`: `deny` rejects all mutations, `allow_list` permits only the canonical
+keys in `HUDU_WRITE_ALLOW`, and `all` permits the SDK's mutation surface. An empty or invalid
+allow-list fails startup. The SDK clients receive the same allow-list plus reads needed by
+helper dependencies; client mode and effect dispatch remain independent restrictions.
+Writes default to dry-run previews; execution requires `dry_run:false`, and destructive
+operations additionally require exact `confirm`. A confirmation string is not human consent.
+Discovery reports deployment-policy refusals as unreachable.
+
+`HUDU_WRITE_POLICY` stays a **deployment-wide** decision, not a per-caller one. Per-caller
+credentials make each caller's Hudu role an external authority too, but that authority is not ours
+to trust and cannot be allowed to widen this server's surface: the server-side policy is the floor,
+`deny` by default, and it holds even when a caller presents a key whose Hudu role could write. The
+same applies to `HUDU_SECRET_READS` and `HUDU_SEARCH_RESOURCES` — all three narrow what *this
+server* will ever offer, independent of what any one caller's key might otherwise permit.
+
+`HUDU_SECRET_READS` governs the other thing no write policy covers: reads that return a plaintext
+credential. `asset_passwords.get` returns `password` and `otp_secret` as an ordinary read, and the
+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
+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
+resources. Refusals are `POLICY_DENIED` and appear as unreachable rows in `hudu_list_operations`.
+
+All SDK clients keep default redaction enabled, including when `HUDU_SECRET_READS=allow`.
+That flag permits credential-resource operations; it never enables plaintext results. The
+SDK masks credential fields and confidential or unclassified custom fields as `[REDACTED]`.
+Untyped fields may therefore be masked even when an external layout calls them public.
+Under `deny`, both company-context paths additionally project password rows to the summary
+field allow-list, dropping free-text descriptions and unknown future fields. No extra layout
+lookups are needed. The common result
+boundary also uses the SDK redactor with `otp_seed`, `recovery_code`, and `recovery_codes`
+as additional secret keys, preserving protections absent from the SDK's default key list.
+
+Result text is a JSON envelope labelled `untrusted_data`; its fixed instruction marks both
+text and `structuredContent` as data, never instructions or authorization to invoke tools.
+
+`HUDU_SEARCH_RESOURCES` is the read-edge counterpart: it narrows which resources the cross-resource
+reads — `hudu_search` and `hudu_resolve_any`, plus the same operations reached through `hudu_read`
+— may offer and query, because a Hudu API key inherits its user's role and may read fewer than the
+SDK's eight searchable resources. Unset means the full set; set it to what the credential can read so
+the schema never advertises a guaranteed-empty read. A per-resource read failure, and an auth failure
+thrown by the resolve fan-out, are reported as unavailable — never with Hudu's own authorization
+message, which is a fact about the calling credential, not the caller's query.
+
+Under `http` each caller's search scope starts cold, so `hudu_search` defaults to `tier:"auto"`
+rather than `"index"`: it answers from Hudu search immediately and builds the body index in the
+background, so a caller's later search is body-aware without the first one awaiting a corpus-wide
+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.
+
+## Development
+
+```
+npm install
+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
+review of the client authority, operation enums and redaction regressions. Docker uses `npm ci`.
+
+## Deployment
+
+`Dockerfile` builds a non-root runtime image. The healthcheck is liveness-only and deliberately does
+not call Hudu — otherwise an upstream outage would cycle the container, turning a partial failure
+into a total one.
+
+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
+it, or share the network with the client that calls it. Copy `.env.example` to `.env` and fill it
+in, then deploy from a clean git checkout with:
+
+    scripts/deploy.sh
+
+The script tags the build with the git short SHA of HEAD (`iit-mcp-hudu-iit-mcp-hudu:<sha>`) —
+never `:latest` — so the running container is always tied to a commit.
+
+### Rolling back
+
+A rebuild cannot touch a previous tag, so it stays resolvable in the local image store. Roll back
+from the same checkout — and only from it:
+
+    docker image inspect iit-mcp-hudu-iit-mcp-hudu:<previous-sha> >/dev/null  # must exist locally
+    HUDU_IMAGE_TAG=<previous-sha> docker compose up -d --no-build --pull never
+
+`--no-build` and `--pull never` are not optional: the service declares both `image` and `build`,
+so without them Compose would fall back to pulling — or building the current source under the old
+tag — if the image is missing, a rollback that deploys the new code instead. The compose file
+also pins `pull_policy: never` as the backstop for any invocation, and the `docker image inspect`
+line makes a pruned or absent image fail loudly before anything is started.
+
+The image that was running before the first tagged deploy was `:latest` (unpinned); until a newer
+pinned tag exists it remains the rollback target via the same two commands with `latest`.
+
+## Release checklist
+
+- Server identity (`name` / `version` reported in `initialize`) is hardcoded in `src/tools/server.ts`,
+  because `rootDir: "src"` forbids importing `package.json` from across the repo root. Bump it there
+  as well as in `package.json`.
+- `BUILT_AGAINST_PLAN_HASH` in `src/tools.ts` pins the SDK catalogue this server was built against.
+  If its test fails after an SDK upgrade, re-read the catalogue and re-check the 19 registered tools,
+  then move the constant. Never move it to make CI green — that is the one thing it exists to stop.

package/dist/auth.d.ts

@@ -0,0 +1,51 @@
+/**
+ * auth.ts — caller authentication for the HTTP transport.
+ *
+ * Two per-request headers answer different questions:
+ *
+ * - `X-Hudu-Api-Key` is the caller's own Hudu key. Under the `http` transport the server normally
+ *   holds no Hudu credential of its own (an operator may set an optional `HUDU_API_KEY` default for
+ *   requests that bring none): the client supplies the key per request,
+ *   scoped per user or per agent to match how the connection is configured. That key is
+ *   what actually reaches Hudu, so a caller can read exactly what its own Hudu role permits and no
+ *   more.
+ * - `X-Hudu-Base-Url` is the origin that key belongs to. It is not a secret — the caller supplied
+ *   it and only ever sees its own value — but it decides which Hudu tenant the key is presented
+ *   to, so it is scoped exactly like the key: per request, single-valued, absent when duplicated,
+ *   and never in the server's config surface or tool schemas.
+ *
+ * The legacy `X-MCP-Token` shared-secret gate is gone (see the 2026-09-29 amendment to the design
+ * spec): the transport boundary is the private, unpublished network the listener must stay on. A
+ * client that still sends `x-mcp-token` is answered exactly as if the header were not there.
+ *
+ * Neither header ever appears in a tool's input schema. See design spec §5.4.
+ */
+/**
+ * The header carrying the caller's Hudu API key.
+ *
+ * Fixed rather than configurable: it is the wire contract clients are built to send, and making it a
+ * knob would let a deployment and its only consumer disagree silently. The value is per request, so
+ * it never enters the server's config surface, logs, or tool schemas.
+ */
+export declare const HUDU_KEY_HEADER = "x-hudu-api-key";
+/**
+ * The header carrying the caller's Hudu base URL — the origin its key belongs to.
+ *
+ * Sibling of {@link HUDU_KEY_HEADER}: fixed rather than configurable, per request, and never in
+ * the server's config surface or tool schemas. It is not a secret — the caller supplied it and
+ * only ever sees its own value — so it is not bound by the key's no-logging rule; the
+ * single-valued rule still applies, though: a base URL presented twice is absent, exactly as with
+ * the key.
+ */
+export declare const HUDU_BASE_URL_HEADER = "x-hudu-base-url";
+/** Read the caller's per-request Hudu API key from request headers. */
+export declare function readHuduKey(headers: Record<string, string | string[] | undefined>): string | undefined;
+/** Read the caller's per-request Hudu base URL from request headers. */
+export declare function readHuduBase(headers: Record<string, string | string[] | undefined>): string | undefined;
+/**
+ * Collapse a web `Headers` bag into the lowercased record shape the readers expect.
+ *
+ * A header given twice becomes an array, which the readers treat as absent — see
+ * {@link readSingleHeader}. That is the whole reason this cannot just be `Object.fromEntries`.
+ */
+export declare function headerRecord(headers: Headers): Record<string, string | string[] | undefined>;

package/dist/auth.js

@@ -0,0 +1,84 @@
+/**
+ * auth.ts — caller authentication for the HTTP transport.
+ *
+ * Two per-request headers answer different questions:
+ *
+ * - `X-Hudu-Api-Key` is the caller's own Hudu key. Under the `http` transport the server normally
+ *   holds no Hudu credential of its own (an operator may set an optional `HUDU_API_KEY` default for
+ *   requests that bring none): the client supplies the key per request,
+ *   scoped per user or per agent to match how the connection is configured. That key is
+ *   what actually reaches Hudu, so a caller can read exactly what its own Hudu role permits and no
+ *   more.
+ * - `X-Hudu-Base-Url` is the origin that key belongs to. It is not a secret — the caller supplied
+ *   it and only ever sees its own value — but it decides which Hudu tenant the key is presented
+ *   to, so it is scoped exactly like the key: per request, single-valued, absent when duplicated,
+ *   and never in the server's config surface or tool schemas.
+ *
+ * The legacy `X-MCP-Token` shared-secret gate is gone (see the 2026-09-29 amendment to the design
+ * spec): the transport boundary is the private, unpublished network the listener must stay on. A
+ * client that still sends `x-mcp-token` is answered exactly as if the header were not there.
+ *
+ * Neither header ever appears in a tool's input schema. See design spec §5.4.
+ */
+/**
+ * The header carrying the caller's Hudu API key.
+ *
+ * Fixed rather than configurable: it is the wire contract clients are built to send, and making it a
+ * knob would let a deployment and its only consumer disagree silently. The value is per request, so
+ * it never enters the server's config surface, logs, or tool schemas.
+ */
+export const HUDU_KEY_HEADER = 'x-hudu-api-key';
+/**
+ * The header carrying the caller's Hudu base URL — the origin its key belongs to.
+ *
+ * Sibling of {@link HUDU_KEY_HEADER}: fixed rather than configurable, per request, and never in
+ * the server's config surface or tool schemas. It is not a secret — the caller supplied it and
+ * only ever sees its own value — so it is not bound by the key's no-logging rule; the
+ * single-valued rule still applies, though: a base URL presented twice is absent, exactly as with
+ * the key.
+ */
+export const HUDU_BASE_URL_HEADER = 'x-hudu-base-url';
+/**
+ * Read a single-valued header, tolerating Node's array-valued header shape.
+ *
+ * A duplicated header is treated as absent rather than trusting the first value: a request that
+ * presents two different credentials is malformed, and picking one is how request-smuggling bugs
+ * start.
+ */
+function readSingleHeader(headers, name) {
+    const raw = headers[name];
+    if (typeof raw === 'string')
+        return raw;
+    if (Array.isArray(raw) && raw.length === 1)
+        return raw[0];
+    return undefined;
+}
+/** Read the caller's per-request Hudu API key from request headers. */
+export function readHuduKey(headers) {
+    return readSingleHeader(headers, HUDU_KEY_HEADER);
+}
+/** Read the caller's per-request Hudu base URL from request headers. */
+export function readHuduBase(headers) {
+    return readSingleHeader(headers, HUDU_BASE_URL_HEADER);
+}
+/**
+ * Collapse a web `Headers` bag into the lowercased record shape the readers expect.
+ *
+ * A header given twice becomes an array, which the readers treat as absent — see
+ * {@link readSingleHeader}. That is the whole reason this cannot just be `Object.fromEntries`.
+ */
+export function headerRecord(headers) {
+    const out = {};
+    headers.forEach((value, name) => {
+        const key = name.toLowerCase();
+        const existing = out[key];
+        if (existing === undefined)
+            out[key] = value;
+        else if (Array.isArray(existing))
+            existing.push(value);
+        else
+            out[key] = [existing, value];
+    });
+    return out;
+}
+//# sourceMappingURL=auth.js.map

package/dist/base-hosts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * base-hosts.ts — the optional allow-list for client-supplied Hudu origins.
+ *
+ * Under `http` a caller names the origin its key is presented to (`x-hudu-base-url`), which makes
+ * this server an outbound HTTP client for whoever can reach the listener. The SDK only checks the
+ * scheme and that there is no path, so when `HUDU_ALLOWED_BASE_HOSTS` is set this is what keeps a
+ * caller from pointing the server at an internal host or a hostile one.
+ */
+/**
+ * Whether `baseUrl`'s host is permitted by `allowed`.
+ *
+ * An entry is an exact hostname (`hudu.example.com`) or a `*.` suffix (`*.example.com`) that
+ * matches subdomains only, never the bare domain. Unset (`undefined`) permits everything at this
+ * level; the http server layers the effective policy on top (default-only when a default origin is
+ * set, bring-your-own-origin when it is not). A URL that does not parse is refused rather than
+ * passed through, so the SDK's own error is never the gate.
+ */
+export declare function baseHostAllowed(baseUrl: string, allowed: readonly string[] | undefined): boolean;
+/** The origin of `url`, or `undefined` when it does not parse. Used to compare against the default. */
+export declare function originOf(url: string): string | undefined;

package/dist/base-hosts.js

@@ -0,0 +1,39 @@
+/**
+ * base-hosts.ts — the optional allow-list for client-supplied Hudu origins.
+ *
+ * Under `http` a caller names the origin its key is presented to (`x-hudu-base-url`), which makes
+ * this server an outbound HTTP client for whoever can reach the listener. The SDK only checks the
+ * scheme and that there is no path, so when `HUDU_ALLOWED_BASE_HOSTS` is set this is what keeps a
+ * caller from pointing the server at an internal host or a hostile one.
+ */
+/**
+ * Whether `baseUrl`'s host is permitted by `allowed`.
+ *
+ * An entry is an exact hostname (`hudu.example.com`) or a `*.` suffix (`*.example.com`) that
+ * matches subdomains only, never the bare domain. Unset (`undefined`) permits everything at this
+ * level; the http server layers the effective policy on top (default-only when a default origin is
+ * set, bring-your-own-origin when it is not). A URL that does not parse is refused rather than
+ * passed through, so the SDK's own error is never the gate.
+ */
+export function baseHostAllowed(baseUrl, allowed) {
+    if (allowed === undefined)
+        return true;
+    let host;
+    try {
+        host = new URL(baseUrl).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    return allowed.some((entry) => entry.startsWith('*.') ? host.endsWith(entry.slice(1)) : host === entry);
+}
+/** The origin of `url`, or `undefined` when it does not parse. Used to compare against the default. */
+export function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=base-hosts.js.map

package/dist/config.d.ts

@@ -0,0 +1,86 @@
+/**
+ * config.ts — the process's entire configuration surface, validated once at boot.
+ *
+ * Every knob is an environment variable. The server refuses to start on an invalid config rather
+ * than failing at the first tool call: a missing credential discovered by a model mid-conversation
+ * is a far worse failure than a container that never came up.
+ *
+ */
+import * as z from 'zod';
+/**
+ * `stdio` is the local path (Claude Code, Claude Desktop, VS Code): one process, one credential,
+ * the process boundary IS the trust boundary. `http` is the remote path (an HTTP MCP client)
+ * and takes the caller's Hudu credential per request.
+ */
+export declare const TRANSPORTS: readonly ["stdio", "http"];
+export type Transport = (typeof TRANSPORTS)[number];
+/**
+ * The deployment's authority over `hudu_read / hudu_write / hudu_delete`'s write surface.
+ *
+ * `deny` is the default on purpose: an operator who forgets the variable gets a read-only server,
+ * never an open one. `all` is today's behaviour and has to be typed out deliberately.
+ */
+export declare const WRITE_POLICIES: readonly ["deny", "allow_list", "all"];
+export type WritePolicy = (typeof WRITE_POLICIES)[number];
+/**
+ * The deployment's authority over reads that can return a plaintext credential.
+ *
+ * `asset_passwords.get` returns `password` and `otp_secret` in plaintext as an ordinary read, so no
+ * write policy touches it — so it needs its own flag that closes both reachable paths in one place. `deny` is the default for the same reason
+ * {@link WRITE_POLICIES} defaults that way: an operator who forgets the variable gets a server that
+ * cannot hand a secret to a model, never one that can.
+ */
+export declare const SECRET_READ_POLICIES: readonly ["deny", "allow"];
+export type SecretReadPolicy = (typeof SECRET_READ_POLICIES)[number];
+declare const schema: z.ZodObject<{
+    HUDU_BASE_URL: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    HUDU_API_KEY: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    HUDU_ALLOWED_BASE_HOSTS: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string[] | undefined, string | undefined>>;
+    HUDU_ALLOW_ANY_BASE_HOST: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "true" | "false">>;
+    MCP_TRANSPORT: z.ZodDefault<z.ZodEnum<{
+        stdio: "stdio";
+        http: "http";
+    }>>;
+    HUDU_SEARCH_MAX_INDEX_PAGES: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    HUDU_SEARCH_RESOURCES: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string[] | undefined, string | undefined>>;
+    HUDU_READ_ONLY: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "true" | "false">>;
+    HUDU_WRITE_POLICY: z.ZodDefault<z.ZodEnum<{
+        deny: "deny";
+        allow_list: "allow_list";
+        all: "all";
+    }>>;
+    HUDU_WRITE_ALLOW: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string[], string | undefined>>;
+    HUDU_SECRET_READS: z.ZodDefault<z.ZodEnum<{
+        deny: "deny";
+        allow: "allow";
+    }>>;
+    PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+    }>>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof schema>;
+/**
+ * Parse and validate configuration from an environment-shaped record.
+ *
+ * Takes the environment as an argument rather than reading `process.env` directly so the failure
+ * paths are testable without mutating global state.
+ *
+ * @throws {ConfigError} when any variable is missing or malformed. The message lists every problem
+ *   at once — a boot loop that surfaces one missing variable per restart wastes real minutes.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
+/** Thrown only by {@link loadConfig}. Never carries a credential value — only variable names. */
+export declare class ConfigError extends Error {
+    readonly name = "ConfigError";
+}
+export {};