iit-mcp-autotask 0.38.7 → 0.38.8

package/README.md

@@ -317,22 +317,21 @@ above it; with neither variable set the feature refuses). `format: 'tsv'` with `
 TSV table to the file (the result carries the path, never the table); `latest` and `note_chars` still
 cannot combine with it. And the value must be a path **relative** to that root that names
 a file (a trailing separator, an absolute path, a NUL byte, and a target that is an existing
-directory are all refused). **Nothing outside the root is ever created,
+directory are all refused). **An existing file is never overwritten**: the call is refused before any
+vendor request, naming the path (pass a new path or remove the old file). **Nothing outside the root is ever created,
 file or directory**: the deepest existing ancestor of the target is canonicalised (`realpath`) and
 checked against the resolved root *before* any directory is created, so a symlinked parent — even
 with a deep sub-path — is refused with zero filesystem effect; only then are the missing directories
 made and the resolved parent re-verified. The **write itself re-enforces both rules at write time**
 (validation and the write are separate steps): it re-resolves the parent — which must still be inside
-the root — refuses a target that is not a regular file, and opens with `O_NOFOLLOW`, so a symlink
-swapped in after validation is never followed. A dangling symlinked parent is the same typed refusal,
+the root — and opens with `O_EXCL | O_NOFOLLOW`, so anything swapped in at the target after validation
+(a symlink, a file, a directory) is refused, never followed or truncated. A dangling symlinked parent is the same typed refusal,
 and every filesystem failure crosses as that typed refusal naming the error code, never an OS message
 (those embed the caller's path). The root itself may be a symlink — containment is then evaluated
 against its canonical target. Under stdio the caller already owns the filesystem, so this is
 containment (a caller path can never make the server create or write outside the root), not a defence
-against a same-user process racing the server. One literal case the containment statement does not
-cover: a hard link placed at the validated path is a regular file to `lstat`, and `O_NOFOLLOW` does not
-apply to it, so the write can land on an inode that is also named outside the root — hard links cannot
-be detected portably, so there is no portable fix.
+against a same-user process racing the server. A hard link at the target path is an existing entry,
+so `O_EXCL` refuses it too.
 
 The walk stops at 10,000 rows with an explicit truncation note in the summary (`hasMore: true` then
 means the cap, not only the query limit). The call is refused outright on the `http` transport (the
@@ -529,12 +528,13 @@ autotask-mcp                    # the live session
 
 | Path | Behaviour |
 |------|-----------|
-| `stdio` boot (env) | **boot refusal**, exit 1, naming the variable, the anomaly, the length and the load recipe — never a character of the value. The value is loaded through the SDK's own canonical loader (`loadAutotaskCredentialsFromEnv`), so this process has exactly one parser: the shell-equivalent one that strips a surrounding quote pair, drops a CRLF's CR and trims edge whitespace. |
+| `stdio` boot (env) | **boot refusal**, exit 1, naming the variable, the SDK's problem, the length and the load recipe — never a character of the value. One check, the SDK's own `credentialShapeProblem`, on every intake path. |
 | `http` per request | **before any client is constructed**, the three `X-Autotask-*` identity headers (and the impersonation header when present) are shape-checked. A malformed one answers the typed `CREDENTIAL_MALFORMED` envelope: `category: "validation"`, `retryable: false`, the anomaly names, and a `suggestedAction` naming the env-load pitfall. **Zero vendor wire** — nothing was dialed, so a `401` shape would be a lie, and `retryable: false` is what stops a retry loop against a lock-sensitive account. |
 | vendor `401` | the envelope gains `credentialShape: "anomalous"` + the SDK's value-free `shapeDiagnostic` + the load-recipe `suggestedAction` when the credential this request presented shows a shape anomaly; `code`, `category`, `httpStatus`, `retryable` and `message` are unchanged. With **clean** values the envelope is byte-identical to the pinned `UNAUTHORIZED` one. |
 
-Anomaly names reported: `surrounding_single_quotes`, `surrounding_double_quotes`, `carriage_return`,
-`newline`, `edge_whitespace`. **Values are never printed** — lengths, two-character prefixes and
+Anomalies are reported in the SDK's wording, the first problem per value: `leading whitespace`,
+`trailing whitespace`, `single- or double-quote surrounding the value`, `carriage return`,
+`line feed`. **Values are never printed** — lengths, two-character prefixes and
 anomaly names only. Every other gate is unchanged, and the shape check runs before them, at the
 boundary.
 
@@ -564,7 +564,7 @@ material).
 | Code | Category | Retryable | When |
 |------|----------|-----------|------|
 | `CREDENTIAL_MISSING` | `auth` | no | no credential on the request and no server-held default, or a partial tuple (all-or-nothing) |
-| `CREDENTIAL_MALFORMED` | `validation` | no | a credential value's **shape** cannot be right (quote pair / CR / edge whitespace) — refused before any client is constructed, zero wire; `anomalies` lists the artifacts and `suggestedAction` names the env-load pitfall |
+| `CREDENTIAL_MALFORMED` | `validation` | no | a credential value's **shape** cannot be right (quote pair / CR / LF / edge whitespace) — refused before any client is constructed, zero wire; `anomalies` lists the artifacts and `suggestedAction` names the env-load pitfall |
 | `UNAUTHORIZED` | `auth` | no | the vendor rejected a credential that **was** sent (401/403). With anomalous values this envelope is annotated (`credentialShape`, `shapeDiagnostic`, `suggestedAction`); with clean values it is exactly the fixed envelope |
 | `HOST_POLICY_DENIED` | `policy` | no | the origin is absent/unusable/not allow-listed (never the value echoed) |
 

package/dist/access/write-env.js

@@ -3,7 +3,7 @@
  * allow/gate/deny), `AUTOTASK_DEDUP`, `AUTOTASK_WRITE_LIMITS` and `AUTOTASK_TRUSTED_HOST_PROMPT`.
  * Pure: resolution needs only the capability registry. Every problem is collected into one ConfigError.
  */
-import { ConfigError } from '../config/error.js';
+import { ConfigError } from '../config/schema.js';
 import { hashOf } from '../write/canonical.js';
 import { hardRuleFor, MOVE_OPS, writeShape } from '../write/hard-rules.js';
 import { RECORDS, recordById } from '../tools/catalog-data.js';

package/dist/config/load.d.ts

@@ -10,3 +10,19 @@ import { type Config } from './schema.js';
  *   problem at once — a boot loop that surfaces one missing variable per restart wastes real minutes.
  */
 export declare function loadConfig(env?: Record<string, string | undefined>): Config;
+/** The recognised AUTOTASK_* names: the config schema's AUTOTASK_ keys (derived, never hand-listed). */
+export declare function recognisedAutotaskVars(): string[];
+/** The set-but-unrecognised AUTOTASK_* env keys (stale 0.4.x-era vars the server never reads). */
+export declare function unrecognisedAutotaskVars(env: Record<string, string | undefined>): string[];
+/**
+ * The server-held credential defaults as a set (or `undefined` when any member is unset — the
+ * tuple is all-or-nothing on the config surface; see the module docblock for why).
+ */
+export declare function serverCredentialDefaults(config: Config): {
+    apiIntegrationCode: string;
+    userName: string;
+    secret: string;
+    impersonationResourceId?: string;
+} | undefined;
+/** True when a full server-held credential tuple is present (the discouraged `http` default). */
+export declare function hasServerCredentialDefaults(config: Config): boolean;

package/dist/config/load.js

@@ -16,10 +16,9 @@
  * presented to the `AUTOTASK_BASE_URL` default origin (never to a caller-named one).
  */
 // `loadConfig`: the environment in, a validated Config out (issue #91).
-import { MALFORMED_CREDENTIAL_REFUSAL, detectCredentialShape, malformedCredentialBootMessage } from '../credential.js';
-import { CONFIG_FIELDS, schema } from './schema.js';
-import { unrecognisedAutotaskVars, loadServerCredentials } from './credentials.js';
-import { ConfigError } from './error.js';
+import { credentialShapeProblem } from 'node-autotask';
+import { malformedCredentialBootMessage } from '../credential.js';
+import { CONFIG_FIELDS, ConfigError, schema } from './schema.js';
 /**
  * Parse and validate configuration from an environment-shaped record.
  *
@@ -34,25 +33,17 @@ export function loadConfig(env = process.env) {
     const parsed = schema.safeParse(env);
     // The pre-dispatch credential shape gate (issue #4a). Runs BEFORE the schema verdict is thrown,
     // so a malformed load is reported alongside (or instead of) the structural problems rather than
-    // being masked by them, and it names the anomaly + the load recipe in one message. Nothing here
-    // dials: the check is pure string inspection.
+    // being masked by them, and it names the SDK's problem + the load recipe in one message. Nothing
+    // here dials: the check is pure string inspection (the SDK's `credentialShapeProblem`, whose
+    // problem string is value-free).
     const shapeIssues = [];
     for (const name of ['AUTOTASK_API_INTEGRATION_CODE', 'AUTOTASK_USERNAME', 'AUTOTASK_SECRET', 'AUTOTASK_IMPERSONATION_RESOURCE_ID']) {
         const raw = env[name];
         if (raw === undefined || raw.trim() === '')
             continue;
-        const anomalies = detectCredentialShape(raw);
-        if (anomalies.length > 0)
-            shapeIssues.push(`  ${name}: ${malformedCredentialBootMessage(name, anomalies, raw.length)}`);
-    }
-    const intake = loadServerCredentials(env);
-    if (intake.sdkProblem !== undefined) {
-        // The SDK's canonical loader refused a value our own check did not name (or named differently).
-        // Only the SDK's machine CODE is referenced: its MESSAGE embeds a value summary
-        // (`credentialValueSummary` -> a length and a two-character prefix, chunk-PBBFMRI5 `shapeError`),
-        // so quoting it would put characters of a secret into the boot log and the doctor-CLI JSON. The
-        // text served is this server's own, value-free: the loader's verdict and the load recipe.
-        shapeIssues.push(`  ${intake.sdkProblem.code}: ${MALFORMED_CREDENTIAL_REFUSAL}`);
+        const problem = credentialShapeProblem(raw);
+        if (problem !== undefined)
+            shapeIssues.push(`  ${name}: ${malformedCredentialBootMessage(name, problem, raw.length)}`);
     }
     if (parsed.success && shapeIssues.length === 0)
         return parsed.data;
@@ -79,4 +70,36 @@ export function loadConfig(env = process.env) {
         ? `Invalid configuration (credential intake refused a value):\n${all.join('\n')}${tail}`
         : `Invalid configuration:\n${all.join('\n')}${tail}`);
 }
+/** The recognised AUTOTASK_* names: the config schema's AUTOTASK_ keys (derived, never hand-listed). */
+export function recognisedAutotaskVars() {
+    return Object.keys(CONFIG_FIELDS.shape).filter((k) => k.startsWith('AUTOTASK_')).sort();
+}
+/** The set-but-unrecognised AUTOTASK_* env keys (stale 0.4.x-era vars the server never reads). */
+export function unrecognisedAutotaskVars(env) {
+    const recognised = new Set(recognisedAutotaskVars());
+    return Object.keys(env).filter((k) => k.startsWith('AUTOTASK_') && !recognised.has(k)).sort();
+}
+/**
+ * The server-held credential defaults as a set (or `undefined` when any member is unset — the
+ * tuple is all-or-nothing on the config surface; see the module docblock for why).
+ */
+export function serverCredentialDefaults(config) {
+    if (config.AUTOTASK_API_INTEGRATION_CODE === undefined ||
+        config.AUTOTASK_USERNAME === undefined ||
+        config.AUTOTASK_SECRET === undefined) {
+        return undefined;
+    }
+    return {
+        apiIntegrationCode: config.AUTOTASK_API_INTEGRATION_CODE,
+        userName: config.AUTOTASK_USERNAME,
+        secret: config.AUTOTASK_SECRET,
+        ...(config.AUTOTASK_IMPERSONATION_RESOURCE_ID !== undefined
+            ? { impersonationResourceId: config.AUTOTASK_IMPERSONATION_RESOURCE_ID }
+            : {}),
+    };
+}
+/** True when a full server-held credential tuple is present (the discouraged `http` default). */
+export function hasServerCredentialDefaults(config) {
+    return serverCredentialDefaults(config) !== undefined;
+}
 //# sourceMappingURL=load.js.map

package/dist/config/schema.d.ts

@@ -1,5 +1,55 @@
-/** The configuration schema: the field table and the validated Config type (issue #91). */
+/**
+ * The configuration schema (issue #91): the closed value sets, the small parsers the fields use, the
+ * field table, the validated Config type and the boot error.
+ */
 import * as z from 'zod';
+/** `stdio` = local path (Claude Code / Claude Desktop / VS Code); `http` = remote (gateway). */
+export declare const TRANSPORTS: readonly ["stdio", "http"];
+export type Transport = (typeof TRANSPORTS)[number];
+/**
+ * The deployment profile (0.6.0). `readonly` (the default) serves reads only and holds no state;
+ * `operator` adds the preview/apply write path (`autotask_write`, `autotask_apply`), which needs a
+ * AUTOTASK_WRITE, a state dir and a run scope (see `src/write/runtime.ts`).
+ */
+export declare const PROFILES: readonly ["readonly", "operator"];
+export type Profile = (typeof PROFILES)[number];
+/** The optional toolsets `AUTOTASK_TOOLSETS` selects; `core` is always registered. */
+export declare const TOOLSETS: readonly ["service", "records", "finance"];
+export type Toolset = (typeof TOOLSETS)[number];
+/** The per-tenant read-cache preset every client this server builds gets. */
+export declare const CACHE_PRESETS: readonly ["on", "off"];
+export type CachePreset = (typeof CACHE_PRESETS)[number];
+/** The vendor's hard cap on requests per hour per integration (the local limiter must not exceed it). */
+export declare const VENDOR_HOURLY_CAP = 10000;
+/**
+ * A run scope: the companies one operator principal may write in this run. `{all: true}` means the
+ * policy's own scope; company ids are intersected with it, so a run scope can only narrow.
+ */
+export declare const RUN_SCOPE: z.ZodUnion<readonly [z.ZodObject<{
+    all: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+    companyIds: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>]>;
+/** True for an address only this host can reach (the HTTP bind decides what boot requires). */
+export declare function isLoopbackHost(host: string): boolean;
+/** A comma list of hostnames (lowercased, de-duplicated), or undefined when unset or blank. */
+export declare function parseHostList(raw: string | undefined): string[] | undefined;
+/** `AUTOTASK_TOOLSETS` parsed once: a comma list of toolset names, `all` = every toolset. */
+export declare function parseToolsets(raw: string | undefined): string[];
+/**
+ * A plausible hostname label (RFC 952/1123): 1-63 lowercase alphanumerics + hyphens, no leading or
+ * trailing hyphen. The `*` wildcard is not a real label: it is legal only as the first label of a
+ * `*.` suffix entry, which the caller strips before delegating here.
+ */
+export declare const HOST_LABEL: RegExp;
+/** Whether an entry could match a real hostname, or only a typo (a silent dead entry). */
+export declare function isPlausibleHost(entry: string): boolean;
+/** Blank-to-undefined preprocessor: `VAR=` (a copied `.env.example` line) means "unset". */
+export declare const blankToUndefined: z.ZodPreprocess<z.ZodString, unknown>;
+/** Thrown only by {@link loadConfig}. Never carries a credential value — only variable names. */
+export declare class ConfigError extends Error {
+    readonly name = "ConfigError";
+}
 export declare const CONFIG_FIELDS: z.ZodObject<{
     MCP_TRANSPORT: z.ZodDefault<z.ZodEnum<{
         stdio: "stdio";

package/dist/config/schema.js

@@ -1,8 +1,69 @@
-/** The configuration schema: the field table and the validated Config type (issue #91). */
+/**
+ * The configuration schema (issue #91): the closed value sets, the small parsers the fields use, the
+ * field table, the validated Config type and the boot error.
+ */
 import * as z from 'zod';
-import { TRANSPORTS, PROFILES, TOOLSETS, CACHE_PRESETS, VENDOR_HOURLY_CAP } from './constants.js';
 import { canonicalTimeZone } from '../tools/clock.js';
-import { RUN_SCOPE, isLoopbackHost, parseHostList, parseToolsets, parseBaseHosts, isPlausibleHost, blankToUndefined } from './parse.js';
+/** `stdio` = local path (Claude Code / Claude Desktop / VS Code); `http` = remote (gateway). */
+export const TRANSPORTS = ['stdio', 'http'];
+/**
+ * The deployment profile (0.6.0). `readonly` (the default) serves reads only and holds no state;
+ * `operator` adds the preview/apply write path (`autotask_write`, `autotask_apply`), which needs a
+ * AUTOTASK_WRITE, a state dir and a run scope (see `src/write/runtime.ts`).
+ */
+export const PROFILES = ['readonly', 'operator'];
+/** The optional toolsets `AUTOTASK_TOOLSETS` selects; `core` is always registered. */
+export const TOOLSETS = ['service', 'records', 'finance'];
+/** The per-tenant read-cache preset every client this server builds gets. */
+export const CACHE_PRESETS = ['on', 'off'];
+/** The vendor's hard cap on requests per hour per integration (the local limiter must not exceed it). */
+export const VENDOR_HOURLY_CAP = 10_000;
+/**
+ * A run scope: the companies one operator principal may write in this run. `{all: true}` means the
+ * policy's own scope; company ids are intersected with it, so a run scope can only narrow.
+ */
+export const RUN_SCOPE = z.union([
+    z.object({ all: z.literal(true) }).strict(),
+    z.object({ companyIds: z.array(z.number().int().positive()).min(1).max(1000) }).strict(),
+]);
+/** True for an address only this host can reach (the HTTP bind decides what boot requires). */
+export function isLoopbackHost(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, '');
+    return h === 'localhost' || h === '::1' || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+/** A comma list of hostnames (lowercased, de-duplicated), or undefined when unset or blank. */
+export function parseHostList(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    return [...new Set(raw.split(',').map((h) => h.trim().toLowerCase()).filter((h) => h.length > 0))];
+}
+/** `AUTOTASK_TOOLSETS` parsed once: a comma list of toolset names, `all` = every toolset. */
+export function parseToolsets(raw) {
+    const names = (raw ?? '')
+        .split(',')
+        .map((name) => name.trim().toLowerCase())
+        .filter((name) => name.length > 0);
+    return names.includes('all') ? [...TOOLSETS] : [...new Set(names)];
+}
+/**
+ * A plausible hostname label (RFC 952/1123): 1-63 lowercase alphanumerics + hyphens, no leading or
+ * trailing hyphen. The `*` wildcard is not a real label: it is legal only as the first label of a
+ * `*.` suffix entry, which the caller strips before delegating here.
+ */
+export const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/** Whether an entry could match a real hostname, or only a typo (a silent dead entry). */
+export function isPlausibleHost(entry) {
+    const body = entry.startsWith('*.') ? entry.slice(2) : entry;
+    if (body === '')
+        return false;
+    return body.split('.').every((label) => HOST_LABEL.test(label));
+}
+/** Blank-to-undefined preprocessor: `VAR=` (a copied `.env.example` line) means "unset". */
+export const blankToUndefined = z.preprocess((raw) => (typeof raw === 'string' && raw.trim() === '' ? undefined : raw), z.string());
+/** Thrown only by {@link loadConfig}. Never carries a credential value — only variable names. */
+export class ConfigError extends Error {
+    name = 'ConfigError';
+}
 export const CONFIG_FIELDS = z
     .object({
     MCP_TRANSPORT: z.enum(TRANSPORTS).default('http'),
@@ -52,7 +113,7 @@ export const CONFIG_FIELDS = z
      * with no default origin -> the server REFUSES to boot unless `AUTOTASK_ALLOW_ANY_BASE_HOST`
      * is explicitly `true` (lab-only, warn-logged). Recommended production value: `*.autotask.net`.
      */
-    AUTOTASK_ALLOWED_BASE_HOSTS: z.string().optional().transform(parseBaseHosts),
+    AUTOTASK_ALLOWED_BASE_HOSTS: z.string().optional().transform(parseHostList),
     /**
      * Explicit, warn-logged, LAB-ONLY opt-in that permits boot with neither allow-list nor
      * default origin (any caller-named origin is then accepted). Never set in a production

package/dist/credential.d.ts

@@ -1,8 +1,7 @@
 /**
- * credential.ts — the pre-dispatch shape gate for Autotask credential values, and the value-free
- * description of a credential the operator-facing doctor reports.
+ * credential.ts — the value-free text around the pre-dispatch credential shape gate.
  *
- * Why this exists (2026-10-07 incident, issues #4/#5/#6): a `.env` file may SINGLE-QUOTE a value on
+ * Why the gate exists (2026-10-07 incident, issues #4/#5/#6): a `.env` file may SINGLE-QUOTE a value on
  * purpose (a secret containing `$` must be, so the shell does not expand it). The shell strips those
  * quotes when the file is loaded with `set -a; . ./.env; set +a`; a quote-PRESERVING loader (most
  * `dotenv` variants, a hand-rolled `split('=')`) hands the value over with its quotes intact. Such a
@@ -10,15 +9,9 @@
  * `Secret: 'a$b'` and comes back as an opaque 401 that reads like a rotated credential — on an
  * account where repeated auth failures risk a lock.
  *
- * This module closes that at the boundary, on BOTH intake paths, before any client is constructed.
- * 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), so every structure here is safe to
- * log and to serialize.
- *
- * The anomaly vocabulary and the anomaly NAMES are this package's own (`detectCredentialShape`), so
- * the envelopes and the doctor report stay stable across SDK versions; the SDK's own validator
- * (`credentialShapeProblem` / `INVALID_CREDENTIAL_SHAPE`) is consumed at construction, where it is
- * part of the SDK's contract with its callers.
+ * The verdict is the SDK's `credentialShapeProblem` (one check on both intake paths, before any client
+ * is constructed); its problem string is value-free and is what the boot refusal, the doctor report and
+ * the `CREDENTIAL_MALFORMED` envelope quote. Nothing here inspects, stores or reports a credential VALUE.
  */
 /**
  * The env-load pitfall every shape rejection points at, without claiming which loader was used.
@@ -27,58 +20,9 @@
  * diagnostic is being told the same thing three times, not three different things.
  */
 export declare const CREDENTIAL_LOAD_HINT = "Load the credential the way the file documents: shell-sourced (`set -a; . ./.env; set +a`) or via loadAutotaskCredentialsFromEnv() from node-autotask \u2014 a quote-preserving parser hands the value over with its quotes intact, which the vendor rejects as invalid credentials.";
-/**
- * The shape anomalies a mis-landed credential file load produces, in the order they are reported.
- *
- * `surrounding_single_quotes` is the incident itself. `carriage_return` covers the Windows-edited
- * `.env` (CRLF): the CR and everything after it would be presented as part of the secret.
- */
-export declare const CREDENTIAL_ANOMALIES: readonly ["surrounding_single_quotes", "surrounding_double_quotes", "carriage_return", "newline", "edge_whitespace"];
-export type CredentialAnomaly = (typeof CREDENTIAL_ANOMALIES)[number];
-/**
- * Every anomaly present in `value`, in {@link CREDENTIAL_ANOMALIES} order. Never returns any part
- * of the value.
- *
- * This is deliberately this package's own predicate rather than the SDK's: the anomaly NAMES are
- * what the model-facing refusal and the operator report quote, so they must not move when the SDK's
- * wording does. The truths agree on the incident class — a value the SDK's `credentialShapeProblem`
- * flags is flagged here too — and `test/unit/credential.test.ts` pins that agreement.
- */
-export declare function detectCredentialShape(value: string): readonly CredentialAnomaly[];
 /** The credential-bearing variable whose value is the secret (the one field masked in reports). */
 export declare const SECRET_VARIABLE = "AUTOTASK_SECRET";
 /** The value-free marker a credential character echo is replaced with (the package's redaction style). */
 export declare const SECRET_MARKER = "[REDACTED]";
-/** True when the value would be refused by the pre-dispatch gate on both intake paths. */
-export declare function isMalformedCredential(value: string): 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 (the format marker), or `<1>` for a one-character value. */
-    readonly prefix2: string;
-    /** Every anomaly seen, in {@link CREDENTIAL_ANOMALIES} order. */
-    readonly anomalies: 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 `<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 shape report for one credential-bearing variable: metadata only, never a value. */
-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;
 /** The one-line, value-free boot refusal message for a malformed credential variable. */
-export declare function malformedCredentialBootMessage(name: string, anomalies: readonly string[], length: number): string;
-/**
- * The server's OWN refusal text for the SDK loader's `INVALID_CREDENTIAL_SHAPE` verdict (issue #4).
- * Built from the loader's machine code only — the SDK's message embeds a value summary
- * (a length and a two-character prefix), so it is never quoted. Value-free: variable names, the
- * loader's verdict, and the load recipe; no length, no prefix, no character of any value.
- */
-export declare const MALFORMED_CREDENTIAL_REFUSAL: string;
+export declare function malformedCredentialBootMessage(name: string, problem: string, length: number): string;

package/dist/credential.js

@@ -1,8 +1,7 @@
 /**
- * credential.ts — the pre-dispatch shape gate for Autotask credential values, and the value-free
- * description of a credential the operator-facing doctor reports.
+ * credential.ts — the value-free text around the pre-dispatch credential shape gate.
  *
- * Why this exists (2026-10-07 incident, issues #4/#5/#6): a `.env` file may SINGLE-QUOTE a value on
+ * Why the gate exists (2026-10-07 incident, issues #4/#5/#6): a `.env` file may SINGLE-QUOTE a value on
  * purpose (a secret containing `$` must be, so the shell does not expand it). The shell strips those
  * quotes when the file is loaded with `set -a; . ./.env; set +a`; a quote-PRESERVING loader (most
  * `dotenv` variants, a hand-rolled `split('=')`) hands the value over with its quotes intact. Such a
@@ -10,15 +9,9 @@
  * `Secret: 'a$b'` and comes back as an opaque 401 that reads like a rotated credential — on an
  * account where repeated auth failures risk a lock.
  *
- * This module closes that at the boundary, on BOTH intake paths, before any client is constructed.
- * 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), so every structure here is safe to
- * log and to serialize.
- *
- * The anomaly vocabulary and the anomaly NAMES are this package's own (`detectCredentialShape`), so
- * the envelopes and the doctor report stay stable across SDK versions; the SDK's own validator
- * (`credentialShapeProblem` / `INVALID_CREDENTIAL_SHAPE`) is consumed at construction, where it is
- * part of the SDK's contract with its callers.
+ * The verdict is the SDK's `credentialShapeProblem` (one check on both intake paths, before any client
+ * is constructed); its problem string is value-free and is what the boot refusal, the doctor report and
+ * the `CREDENTIAL_MALFORMED` envelope quote. Nothing here inspects, stores or reports a credential VALUE.
  */
 /**
  * The env-load pitfall every shape rejection points at, without claiming which loader was used.
@@ -27,89 +20,13 @@
  * diagnostic is being told the same thing three times, not three different things.
  */
 export const CREDENTIAL_LOAD_HINT = 'Load the credential the way the file documents: shell-sourced (`set -a; . ./.env; set +a`) or via loadAutotaskCredentialsFromEnv() from node-autotask — a quote-preserving parser hands the value over with its quotes intact, which the vendor rejects as invalid credentials.';
-/**
- * The shape anomalies a mis-landed credential file load produces, in the order they are reported.
- *
- * `surrounding_single_quotes` is the incident itself. `carriage_return` covers the Windows-edited
- * `.env` (CRLF): the CR and everything after it would be presented as part of the secret.
- */
-export const CREDENTIAL_ANOMALIES = [
-    'surrounding_single_quotes',
-    'surrounding_double_quotes',
-    'carriage_return',
-    'newline',
-    'edge_whitespace',
-];
-/**
- * Every anomaly present in `value`, in {@link CREDENTIAL_ANOMALIES} order. Never returns any part
- * of the value.
- *
- * This is deliberately this package's own predicate rather than the SDK's: the anomaly NAMES are
- * what the model-facing refusal and the operator report quote, so they must not move when the SDK's
- * wording does. The truths agree on the incident class — a value the SDK's `credentialShapeProblem`
- * flags is flagged here too — and `test/unit/credential.test.ts` pins that agreement.
- */
-export function detectCredentialShape(value) {
-    const anomalies = [];
-    // The incident, first: quotes preserved by a parser that should have consumed them. Only a
-    // SURROUNDING pair is reported (addressed to the SDK's own `hasSurroundingQuotes` rule).
-    if (value.length >= 2 && value.startsWith("'") && value.endsWith("'"))
-        anomalies.push('surrounding_single_quotes');
-    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"'))
-        anomalies.push('surrounding_double_quotes');
-    // A CR is reported even mid-value; CRLF is caught by the same check.
-    if (value.includes('\r'))
-        anomalies.push('carriage_return');
-    if (value.includes('\n'))
-        anomalies.push('newline');
-    // A trailing space from `KEY=value ` is invisible in most editors and is presented verbatim.
-    if (value.length > 0 && value !== value.trim())
-        anomalies.push('edge_whitespace');
-    return anomalies;
-}
 /** The credential-bearing variable whose value is the secret (the one field masked in reports). */
 export const SECRET_VARIABLE = 'AUTOTASK_SECRET';
 /** The value-free marker a credential character echo is replaced with (the package's redaction style). */
 export const SECRET_MARKER = '[REDACTED]';
-/** True when the value would be refused by the pre-dispatch gate on both intake paths. */
-export function isMalformedCredential(value) {
-    return detectCredentialShape(value).length > 0;
-}
-/**
- * The shape facts an operator-facing surface may report for one credential field. `prefix2` is
- * emitted for values of at least two characters and `<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) };
-}
 /** The one-line, value-free boot refusal message for a malformed credential variable. */
-export function malformedCredentialBootMessage(name, anomalies, length) {
-    return (`${name} holds a value whose shape cannot be right (length ${length}, ${anomalies.join(', ')}); ` +
+export function malformedCredentialBootMessage(name, problem, length) {
+    return (`${name} holds a value whose shape cannot be right (length ${length}, ${problem}); ` +
         `this server refuses to boot rather than present a malformed credential to Autotask (issue #4). ${CREDENTIAL_LOAD_HINT}`);
 }
-/**
- * The server's OWN refusal text for the SDK loader's `INVALID_CREDENTIAL_SHAPE` verdict (issue #4).
- * Built from the loader's machine code only — the SDK's message embeds a value summary
- * (a length and a two-character prefix), so it is never quoted. Value-free: variable names, the
- * loader's verdict, and the load recipe; no length, no prefix, no character of any value.
- */
-export const MALFORMED_CREDENTIAL_REFUSAL = 'one or more credential values were refused by the SDK\'s canonical loader as a malformed shape; ' +
-    'no request was sent. Fix the value in the environment this server reads and reload it. ' +
-    CREDENTIAL_LOAD_HINT;
 //# sourceMappingURL=credential.js.map

package/dist/doctor.js

@@ -1,6 +1,6 @@
-import { serverCredentialDefaults, unrecognisedAutotaskVars } from './config/credentials.js';
+import { serverCredentialDefaults, unrecognisedAutotaskVars } from './config/load.js';
 import {} from './config/schema.js';
-import { describeCredential, isMalformedCredential } from './credential.js';
+import { credentialShapeProblem } from 'node-autotask';
 import { SECRET_MARKER, SECRET_VARIABLE } from './credential.js';
 import { assertPlanHash, BUILT_AGAINST_PLAN_HASH } from './tools/catalog-data.js';
 /** Check one credential-shaped value without ever carrying it out of this function. */
@@ -10,21 +10,23 @@ function credentialCheck(name, value, required) {
         // the `.env.example` placeholder rather than a credential the vendor would see.
         return { name, status: 'absent', shapeOk: false, blocks: required };
     }
-    const shape = describeCredential(value);
-    const malformed = isMalformedCredential(value);
+    const problem = credentialShapeProblem(value);
+    const malformed = problem !== undefined;
     return {
         name,
         status: malformed ? 'malformed' : 'ok',
-        length: shape.length,
+        length: value.length,
         // The SECRET's first two characters are the one place a credential character could cross this
         // boundary: `GET /doctor` is pre-auth and the CLI writes to stdout, while every other surface of
         // this package emits zero characters of a secret (value-scrub to `[REDACTED]`, boot message =
         // length only, envelopes never carry prefixes). The secret is therefore masked with the
         // package's own marker; the identifiers (integration code, username, impersonation id) are not
         // secrets and keep their format prefix, which is what makes the report useful.
-        prefix2: name === SECRET_VARIABLE ? SECRET_MARKER : shape.prefix2,
+        // `<1>` for a one-character value, so the report never implies a one-character secret.
+        prefix2: name === SECRET_VARIABLE ? SECRET_MARKER : value.length >= 2 ? value.slice(0, 2) : '<1>',
         shapeOk: !malformed,
-        anomalies: shape.anomalies,
+        // The SDK's value-free problem string (its first problem only), or none.
+        anomalies: malformed ? [problem] : [],
         // `blocks` is "this field would be refused": an absent-and-required field and a malformed one,
         // and nothing else. A present, well-shaped value never blocks, however much the deployment needs it.
         blocks: malformed,

package/dist/http-guard.js

@@ -18,10 +18,7 @@ import { createHash, timingSafeEqual } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { hostHeaderValidationResponse, localhostAllowedHostnames, localhostAllowedOrigins, originValidationResponse, } from '@modelcontextprotocol/server';
 import * as z from 'zod';
-import { ConfigError } from './config/error.js';
-import { PROFILES, TOOLSETS } from './config/constants.js';
-import { RUN_SCOPE, isLoopbackHost } from './config/parse.js';
-import {} from './config/schema.js';
+import { ConfigError, PROFILES, TOOLSETS, RUN_SCOPE, isLoopbackHost } from './config/schema.js';
 /** The request body cap on the HTTP transport (M10). */
 export const MAX_BODY_BYTES = 1024 * 1024;
 /**

package/dist/http.js

@@ -5,7 +5,7 @@
  * optional for that consumer. The caller's per-request Autotask credential tuple in the
  * `X-Autotask-*` headers — together with the origin in `X-Autotask-Base-Url` — is what the tools
  * use to reach Autotask, unless the optional server-held defaults fill them in (presented to the
- * default origin only) — see `src/auth.ts` and the scope resolver in `src/tools/context.ts`.
+ * default origin only) — see `src/auth.ts` and the scope resolver in `src/tools/context/scope.ts`.
  * The transport boundary is the network: the listener must stay on a private, unpublished network.
  *
  * A request with no Autotask credentials is allowed through so the SDK can serve
@@ -17,7 +17,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { serverCredentialDefaults } from './config/credentials.js';
+import { serverCredentialDefaults } from './config/load.js';
 import {} from './config/schema.js';
 import { runDoctor } from './doctor.js';
 import { SERVER_IDENTITY } from './tools/server.js';

package/dist/main.js

@@ -10,10 +10,8 @@
  * only decision this file makes (the stdio transport is the few lines of `startStdio` below).
  */
 import { createMcpHandler } from '@modelcontextprotocol/server';
-import { ConfigError } from './config/error.js';
-import { loadConfig } from './config/load.js';
-import { serverCredentialDefaults, unrecognisedAutotaskVars } from './config/credentials.js';
-import {} from './config/schema.js';
+import { ConfigError } from './config/schema.js';
+import { loadConfig, serverCredentialDefaults, unrecognisedAutotaskVars } from './config/load.js';
 import { runMoves } from './moves.js';
 import { runDoctor } from './doctor.js';
 import { createLogger } from './logger.js';

package/dist/tools/aggregate.d.ts

@@ -1,4 +1,4 @@
-import type { ToolContext } from './context.js';
+import type { ToolContext } from './context/types.js';
 import { type ToolReturn } from './results/envelope.js';
 /** The SDK aggregate opts this server passes (the SDK's own names). */
 export interface AggregateOpts {

package/dist/tools/catalog-data.js

@@ -15,7 +15,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { CAPABILITIES, CAPABILITY_PLAN_HASHES } from 'node-autotask/capabilities';
-import { ConfigError } from '../config/error.js';
+import { ConfigError } from '../config/schema.js';
 const require = createRequire(import.meta.url);
 /** The installed `node-autotask` package directory (the data files ship at its root). */
 const SDK_PACKAGE_DIR = dirname(require.resolve('node-autotask/package.json'));