@jagilber-org/index-server 1.22.1 → 1.26.1

package/dist/server/certInit.js

@@ -0,0 +1,359 @@
+"use strict";
+/**
+ * Certificate bootstrap module for the `--init-cert` CLI switch.
+ *
+ * Public surface (all exports carry JSDoc per CQ-7):
+ * - {@link validateOptions} : merge defaults, validate, resolve absolute paths
+ * - {@link parseSan}        : split + validate SAN entries
+ * - {@link buildOpenSslArgs}: build argv for `openssl req -x509`
+ * - {@link preflightOpenssl}: verify openssl is callable on PATH
+ * - {@link formatPrintEnv}  : produce env-var lines for the operator
+ * - {@link runCertInit}     : end-to-end pipeline
+ *
+ * Constitution refs:
+ * - SH-4 : every output path is `path.resolve`d and asserted to live under
+ *          the resolved `certDir`.
+ * - SH-6 : this module never disables TLS verification anywhere.
+ * - CQ-1 : lives in its own file so `index-server.ts` stays under budget.
+ * - CQ-6 : every catch surfaces a typed error; no swallowed exceptions.
+ * - OB-3 : failures throw {@link CertInitError} with a stable `code`.
+ * - OB-5 : success and skip paths log at INFO; failures log at ERROR.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOptions = validateOptions;
+exports.parseSan = parseSan;
+exports.buildOpenSslArgs = buildOpenSslArgs;
+exports.preflightOpenssl = preflightOpenssl;
+exports.formatPrintEnv = formatPrintEnv;
+exports.runCertInit = runCertInit;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const logger_1 = require("../services/logger");
+const certInit_types_1 = require("./certInit.types");
+// ── Defaults ──────────────────────────────────────────────────────────────
+/** Default RSA key size when the caller does not specify `--key-bits`. */
+const DEFAULT_KEY_BITS = 2048;
+/** Default validity period in days. */
+const DEFAULT_DAYS = 365;
+/** Default subject CommonName. */
+const DEFAULT_CN = 'localhost';
+/** Default SAN list, covering loopback HTTPS scenarios out of the box. */
+const DEFAULT_SAN = 'DNS:localhost,IP:127.0.0.1';
+/** Default cert filename within `certDir`. */
+const DEFAULT_CERT_FILENAME = 'index-server.crt';
+/** Default key filename within `certDir`. */
+const DEFAULT_KEY_FILENAME = 'index-server.key';
+/** Inclusive minimum value for `--days`. */
+const MIN_DAYS = 1;
+/** Inclusive maximum value for `--days`. */
+const MAX_DAYS = 3650;
+/**
+ * Compute the default cert directory path: `<homedir>/.index-server/certs`.
+ * Used when the caller does not specify `--cert-dir`.
+ *
+ * @returns Absolute path to the default cert directory.
+ */
+function defaultCertDir() {
+    return path_1.default.join(os_1.default.homedir(), '.index-server', 'certs');
+}
+// ── validateOptions ───────────────────────────────────────────────────────
+/**
+ * Validate a partial options bag and return a fully-resolved
+ * {@link CertInitOptions} suitable for {@link runCertInit}.
+ *
+ * Defaults are applied for any field omitted by the caller. All paths are
+ * `path.resolve`d. The function rejects values that violate the v1 contract:
+ * days out of `[MIN_DAYS, MAX_DAYS]`, key-bits not in `{2048, 4096}`, SAN
+ * entries without `DNS:` or `IP:` prefix, empty CN, or output paths that
+ * escape `certDir` (SH-4).
+ *
+ * @param input  Partial options as parsed from the CLI.
+ * @returns      Fully-resolved {@link CertInitOptions}.
+ * @throws       {@link CertInitError} with codes `INVALID_DAYS`,
+ *               `INVALID_KEY_BITS`, `INVALID_SAN`, `INVALID_CN`, or
+ *               `PATH_OUTSIDE_CERT_DIR`.
+ */
+function validateOptions(input) {
+    const certDir = path_1.default.resolve(input.certDir ?? defaultCertDir());
+    const certFile = path_1.default.resolve(input.certFile ?? path_1.default.join(certDir, DEFAULT_CERT_FILENAME));
+    const keyFile = path_1.default.resolve(input.keyFile ?? path_1.default.join(certDir, DEFAULT_KEY_FILENAME));
+    // SH-4: every output path must resolve under the cert dir.
+    assertUnderDir(certFile, certDir, 'certFile');
+    assertUnderDir(keyFile, certDir, 'keyFile');
+    const days = input.days ?? DEFAULT_DAYS;
+    if (!Number.isInteger(days) || days < MIN_DAYS || days > MAX_DAYS) {
+        throw new certInit_types_1.CertInitError('INVALID_DAYS', `days must be an integer in [${MIN_DAYS}, ${MAX_DAYS}], received ${String(days)}`);
+    }
+    const keyBits = input.keyBits ?? DEFAULT_KEY_BITS;
+    if (keyBits !== 2048 && keyBits !== 4096) {
+        throw new certInit_types_1.CertInitError('INVALID_KEY_BITS', `keyBits must be 2048 or 4096, received ${String(keyBits)}`);
+    }
+    const cn = (input.cn ?? DEFAULT_CN).trim();
+    if (cn.length === 0) {
+        throw new certInit_types_1.CertInitError('INVALID_CN', 'cn (CommonName) must not be empty');
+    }
+    const san = input.san ?? DEFAULT_SAN;
+    // Validate SAN early so callers see a clean error before openssl runs.
+    parseSan(san);
+    return {
+        certDir,
+        certFile,
+        keyFile,
+        cn,
+        san,
+        days,
+        keyBits,
+        force: input.force ?? false,
+        printEnv: input.printEnv ?? false,
+    };
+}
+/**
+ * Assert that `target` resolves to a path strictly inside `dir`. Used by the
+ * SH-4 path-traversal guard in {@link validateOptions}.
+ *
+ * @param target  Absolute path to check.
+ * @param dir     Absolute directory path that must contain `target`.
+ * @param label   Human-readable name used in the error message.
+ * @throws        {@link CertInitError} `PATH_OUTSIDE_CERT_DIR` when `target`
+ *                escapes `dir`.
+ */
+function assertUnderDir(target, dir, label) {
+    const rel = path_1.default.relative(dir, target);
+    // SH-4: BOTH conditions are required. Do NOT collapse this to a single check.
+    //   rel.startsWith('..')   catches same-drive parent-dir escape
+    //                          (e.g. C:\certs\..\..\evil  ->  '..\..\evil').
+    //   path.isAbsolute(rel)   catches Windows cross-drive paths (D:\evil) and
+    //                          UNC shares (\\server\share\evil), where
+    //                          path.relative() returns an *absolute* path
+    //                          rather than a '..\..'-prefixed relative one.
+    // Removing either clause silently reintroduces a path-traversal bypass.
+    if (rel.startsWith('..') || path_1.default.isAbsolute(rel)) {
+        throw new certInit_types_1.CertInitError('PATH_OUTSIDE_CERT_DIR', `${label} (${target}) must resolve under cert dir (${dir})`);
+    }
+}
+// ── parseSan ──────────────────────────────────────────────────────────────
+/**
+ * Parse a comma-separated SAN string into individual entries, validating that
+ * each entry has a recognized `DNS:` or `IP:` prefix.
+ *
+ * @param raw  Raw SAN string from the CLI (e.g. `"DNS:host,IP:127.0.0.1"`).
+ * @returns    Array of validated SAN entries with surrounding whitespace
+ *             trimmed.
+ * @throws     {@link CertInitError} `INVALID_SAN` for empty input, trailing
+ *             commas, or entries missing a recognized prefix.
+ */
+function parseSan(raw) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        throw new certInit_types_1.CertInitError('INVALID_SAN', 'san must be a non-empty string');
+    }
+    const parts = raw.split(',');
+    const entries = [];
+    for (const p of parts) {
+        const trimmed = p.trim();
+        if (trimmed.length === 0) {
+            throw new certInit_types_1.CertInitError('INVALID_SAN', `san contains an empty entry (check for trailing/leading commas in "${raw}")`);
+        }
+        if (!trimmed.startsWith('DNS:') && !trimmed.startsWith('IP:')) {
+            throw new certInit_types_1.CertInitError('INVALID_SAN', `san entry "${trimmed}" must start with "DNS:" or "IP:"`);
+        }
+        entries.push(trimmed);
+    }
+    return entries;
+}
+// ── buildOpenSslArgs ──────────────────────────────────────────────────────
+/**
+ * Build the argument array for the OpenSSL `req -x509` invocation that
+ * generates a self-signed certificate. The returned array is suitable for
+ * `child_process.execFile('openssl', args)` — no shell metacharacters are
+ * inserted, and inputs are not interpolated into a command string.
+ *
+ * @param opts  Fully-resolved cert-init options (use {@link validateOptions}
+ *              to produce these).
+ * @returns     Argument array for `openssl`.
+ */
+function buildOpenSslArgs(opts) {
+    return [
+        'req',
+        '-x509',
+        '-newkey', `rsa:${opts.keyBits}`,
+        '-nodes',
+        '-keyout', opts.keyFile,
+        '-out', opts.certFile,
+        '-days', String(opts.days),
+        '-subj', `/CN=${opts.cn}`,
+        '-addext', `subjectAltName=${opts.san}`,
+    ];
+}
+// ── preflightOpenssl ──────────────────────────────────────────────────────
+/**
+ * Verify that `openssl` is callable on PATH. Used as a preflight before any
+ * generation work so that the failure surfaces with a stable
+ * `OPENSSL_NOT_FOUND` code rather than a downstream spawn error.
+ *
+ * @returns The reported version string when openssl is callable.
+ * @throws  {@link CertInitError} `OPENSSL_NOT_FOUND` otherwise.
+ */
+function preflightOpenssl() {
+    let result;
+    try {
+        result = (0, child_process_1.spawnSync)('openssl', ['version'], { stdio: 'pipe', timeout: 5000 });
+    }
+    catch (e) {
+        throw new certInit_types_1.CertInitError('OPENSSL_NOT_FOUND', 'openssl was not found on PATH or could not be invoked. Install OpenSSL and retry. ' +
+            'See https://www.openssl.org/source/ for downloads.', e);
+    }
+    if (!result || result.status !== 0) {
+        const stderr = result?.stderr?.toString().trim() ?? '';
+        throw new certInit_types_1.CertInitError('OPENSSL_NOT_FOUND', `openssl probe failed (status=${String(result?.status)}): ${stderr || 'no output'}. Install OpenSSL and retry.`);
+    }
+    return result.stdout.toString().trim();
+}
+// ── formatPrintEnv ────────────────────────────────────────────────────────
+/**
+ * Format the env-var lines an operator can paste into their shell after a
+ * successful generation, pointing the dashboard at the new cert/key.
+ *
+ * @param opts    Resolved cert-init options.
+ * @param format  Output format. `'auto'` picks `'powershell'` on Win32,
+ *                `'posix'` elsewhere.
+ * @returns       Multi-line string ending with a trailing newline.
+ */
+function formatPrintEnv(opts, format = 'auto') {
+    const resolved = format === 'auto'
+        ? (process.platform === 'win32' ? 'powershell' : 'posix')
+        : format;
+    const posix = [
+        `export INDEX_SERVER_DASHBOARD_TLS=1`,
+        `export INDEX_SERVER_DASHBOARD_TLS_CERT="${opts.certFile}"`,
+        `export INDEX_SERVER_DASHBOARD_TLS_KEY="${opts.keyFile}"`,
+    ].join('\n') + '\n';
+    const ps = [
+        `$env:INDEX_SERVER_DASHBOARD_TLS="1"`,
+        `$env:INDEX_SERVER_DASHBOARD_TLS_CERT="${opts.certFile}"`,
+        `$env:INDEX_SERVER_DASHBOARD_TLS_KEY="${opts.keyFile}"`,
+    ].join('\n') + '\n';
+    if (resolved === 'powershell')
+        return ps;
+    if (resolved === 'posix')
+        return posix;
+    // both
+    return `# POSIX\n${posix}\n# PowerShell\n${ps}`;
+}
+// ── runCertInit ───────────────────────────────────────────────────────────
+/**
+ * Execute the full cert-init pipeline: validate options, preflight openssl,
+ * create `certDir` if missing, run openssl, set restrictive permissions on
+ * POSIX, and emit a structured log line via the existing logger.
+ *
+ * Idempotency: if `certFile` OR `keyFile` already exists and `force` is false,
+ * no openssl invocation is made and a `kind: 'skipped'` result is returned.
+ * Treating only the both-exist case as "skip" would clobber a surviving cert
+ * when the operator deleted/rotated only the key (or vice versa) — `--force`
+ * is required to overwrite *any* existing file.
+ *
+ * @param input  Caller options (typically from the CLI parser). Re-validated
+ *               internally so direct callers do not need to pre-validate.
+ * @returns      A {@link CertInitResult} indicating generated vs skipped.
+ * @throws       {@link CertInitError} for any validation, preflight, or
+ *               execution failure (codes documented on each helper above).
+ */
+async function runCertInit(input) {
+    const opts = validateOptions(input);
+    // Skip if EITHER file exists without --force. Treating only the both-exist
+    // case as "skip" would clobber a surviving cert when the operator deleted /
+    // rotated only the key (or vice versa) — the principle of least surprise is
+    // that --force is required to overwrite *any* existing file on disk.
+    const certExists = fs_1.default.existsSync(opts.certFile);
+    const keyExists = fs_1.default.existsSync(opts.keyFile);
+    const bothExist = certExists && keyExists;
+    const anyExists = certExists || keyExists;
+    if (anyExists && !opts.force) {
+        const reason = bothExist
+            ? 'cert and key files already exist; pass --force to overwrite'
+            : `partial state on disk (cert=${certExists}, key=${keyExists}); pass --force to overwrite`;
+        (0, logger_1.logInfo)('[certInit] skip (files exist; use --force to overwrite)', {
+            cert: opts.certFile,
+            certExists,
+            key: opts.keyFile,
+            keyExists,
+        });
+        return {
+            kind: 'skipped',
+            reason,
+            certFile: opts.certFile,
+            keyFile: opts.keyFile,
+        };
+    }
+    // Preflight openssl AFTER the skip-when-exists check so an idempotent
+    // re-run on a host without openssl (where the cert was generated elsewhere)
+    // still succeeds with a `skipped` result.
+    preflightOpenssl();
+    // Ensure cert dir exists.
+    try {
+        fs_1.default.mkdirSync(opts.certDir, { recursive: true });
+    }
+    catch (e) {
+        throw new certInit_types_1.CertInitError('MKDIR_FAILED', `failed to create cert directory ${opts.certDir}: ${(e instanceof Error) ? e.message : String(e)}`, e);
+    }
+    const args = buildOpenSslArgs(opts);
+    // TOCTOU mitigation: openssl writes the key with the process umask (commonly
+    // 0o022 -> mode 0o644). We narrow the umask to 0o077 around the execFile so
+    // the key is created mode 0o600 from the start, eliminating the world-
+    // readable window between key creation and our explicit chmod below. We
+    // restore the previous umask in `finally` regardless of outcome. On Windows
+    // umask is effectively a no-op (NTFS ACLs are unaffected), so this is safe
+    // cross-platform. See docs/cert_init.md for the residual multi-user note
+    // (defense-in-depth: dedicated user, 0o700 parent dir).
+    const prevUmask = process.umask(0o077);
+    try {
+        (0, child_process_1.execFileSync)('openssl', args, { stdio: 'pipe', timeout: 30000 });
+    }
+    catch (e) {
+        const stderr = e.stderr?.toString().trim() ?? '';
+        const status = e.status;
+        const errorMsg = `openssl req failed (status=${String(status)}): ${stderr || (e instanceof Error ? e.message : String(e))}`;
+        (0, logger_1.logError)('[certInit] openssl invocation failed', { args: args.join(' '), stderr });
+        throw new certInit_types_1.CertInitError('OPENSSL_FAILED', errorMsg, e);
+    }
+    finally {
+        process.umask(prevUmask);
+    }
+    // Belt-and-braces: explicitly narrow key permissions to 0o600 even though
+    // umask 0o077 above should already have produced that mode. Handles the case
+    // where openssl ignores umask on some platforms or where the file pre-existed
+    // (force overwrite). No-op on Windows where chmod semantics differ
+    // (POSIX-mode bits are ignored by NTFS ACLs).
+    if (process.platform !== 'win32') {
+        try {
+            fs_1.default.chmodSync(opts.keyFile, 0o600);
+        }
+        catch (e) {
+            // Non-fatal: log a warning but do not fail the whole operation.
+            // The key was still written successfully.
+            (0, logger_1.logError)('[certInit] failed to chmod private key to 0600', {
+                key: opts.keyFile,
+                error: (e instanceof Error) ? e.message : String(e),
+            });
+        }
+    }
+    (0, logger_1.logInfo)('[certInit] generated certificate', {
+        cert: opts.certFile,
+        key: opts.keyFile,
+        cn: opts.cn,
+        san: opts.san,
+        days: opts.days,
+        keyBits: opts.keyBits,
+        overwritten: bothExist,
+    });
+    return {
+        kind: 'generated',
+        certFile: opts.certFile,
+        keyFile: opts.keyFile,
+        overwritten: bothExist,
+    };
+}

package/dist/server/certInit.types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Type definitions for the `--init-cert` certificate bootstrap subsystem.
+ *
+ * These types are deliberately split out from `certInit.ts` so that test
+ * fixtures and external callers can import the option/result shapes without
+ * pulling in the OpenSSL invocation surface.
+ *
+ * Constitution refs: CQ-7 (JSDoc on public types), AR-1 (smallest type surface
+ * sufficient for the v1 feature).
+ */
+/**
+ * Output format for `--print-env` helper.
+ *
+ * - `posix`        — emit `export NAME="value"` lines (bash, zsh, sh).
+ * - `powershell`   — emit `$env:NAME="value"` lines (Windows PowerShell, pwsh).
+ * - `both`         — emit both, separated by a blank line and platform headers.
+ * - `auto`         — pick `powershell` on Win32, `posix` elsewhere.
+ */
+export type PrintEnvFormat = 'posix' | 'powershell' | 'both' | 'auto';
+/**
+ * Resolved options for a single `runCertInit` invocation.
+ *
+ * All paths must be absolute by the time they reach `runCertInit`. Validation
+ * (path-traversal guard per SH-4, numeric range checks) happens via
+ * `validateOptions` before any filesystem or `openssl` work occurs.
+ */
+export interface CertInitOptions {
+    /** Absolute directory that contains the cert + key (and optionally CA). */
+    certDir: string;
+    /** Absolute path to the server certificate file (PEM). Must resolve under `certDir`. */
+    certFile: string;
+    /** Absolute path to the server private key file (PEM). Must resolve under `certDir`. */
+    keyFile: string;
+    /** Subject CommonName (CN) for the generated certificate. */
+    cn: string;
+    /**
+     * Comma-separated SAN entries, e.g. `DNS:localhost,IP:127.0.0.1`.
+     * Each entry MUST start with a `DNS:` or `IP:` prefix.
+     */
+    san: string;
+    /** Validity period in days. Range: 1..3650 inclusive. */
+    days: number;
+    /** RSA key size in bits. Allowed values: 2048, 4096. */
+    keyBits: 2048 | 4096;
+    /** When true, overwrite existing cert/key files. */
+    force: boolean;
+    /** When true, the dispatcher will print env-var lines after generation. */
+    printEnv: boolean | PrintEnvFormat;
+}
+/**
+ * Result of `runCertInit`. Distinguishes generated vs skipped vs failed paths
+ * so the dispatcher in `index-server.ts` can decide whether to exit, continue,
+ * or surface an error.
+ */
+export type CertInitResult = {
+    kind: 'generated';
+    /** Absolute path to the written certificate file. */
+    certFile: string;
+    /** Absolute path to the written private key file. */
+    keyFile: string;
+    /** True when files were overwritten because `--force` was given. */
+    overwritten: boolean;
+} | {
+    kind: 'skipped';
+    /** Reason the operation was skipped (e.g. files already present). */
+    reason: string;
+    /** Absolute path to the existing certificate file. */
+    certFile: string;
+    /** Absolute path to the existing private key file. */
+    keyFile: string;
+};
+/**
+ * Structured error thrown by `runCertInit` and its helpers. The `code` field
+ * is stable and machine-readable; tests assert on `code`, not on `message`
+ * wording (per OB-3 / TS-12 robustness).
+ */
+export declare class CertInitError extends Error {
+    readonly code: CertInitErrorCode;
+    readonly cause?: unknown | undefined;
+    /**
+     * @param code   Stable machine-readable identifier for the failure class.
+     * @param message Human-readable explanation; safe to surface to operators.
+     * @param cause  Optional underlying cause (e.g. a spawn error or fs error).
+     */
+    constructor(code: CertInitErrorCode, message: string, cause?: unknown | undefined);
+}
+/**
+ * Stable error codes emitted by the cert-init subsystem. New codes may be
+ * appended; existing codes MUST NOT change meaning (semver guarantee for
+ * downstream tooling and test assertions).
+ */
+export type CertInitErrorCode = 'OPENSSL_NOT_FOUND' | 'OPENSSL_FAILED' | 'INVALID_DAYS' | 'INVALID_KEY_BITS' | 'INVALID_SAN' | 'INVALID_CN' | 'PATH_OUTSIDE_CERT_DIR' | 'WRITE_FAILED' | 'MKDIR_FAILED';

package/dist/server/certInit.types.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Type definitions for the `--init-cert` certificate bootstrap subsystem.
+ *
+ * These types are deliberately split out from `certInit.ts` so that test
+ * fixtures and external callers can import the option/result shapes without
+ * pulling in the OpenSSL invocation surface.
+ *
+ * Constitution refs: CQ-7 (JSDoc on public types), AR-1 (smallest type surface
+ * sufficient for the v1 feature).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CertInitError = void 0;
+/**
+ * Structured error thrown by `runCertInit` and its helpers. The `code` field
+ * is stable and machine-readable; tests assert on `code`, not on `message`
+ * wording (per OB-3 / TS-12 robustness).
+ */
+class CertInitError extends Error {
+    code;
+    cause;
+    /**
+     * @param code   Stable machine-readable identifier for the failure class.
+     * @param message Human-readable explanation; safe to surface to operators.
+     * @param cause  Optional underlying cause (e.g. a spawn error or fs error).
+     */
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'CertInitError';
+    }
+}
+exports.CertInitError = CertInitError;

package/dist/server/handshake/fallbackFrames.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure JSON-RPC frame builders used by the handshake fallback paths. No I/O,
+ * no mutable state — these can be safely unit tested in isolation.
+ */
+export interface ForcedInitFrame {
+    jsonrpc: '2.0';
+    id: number;
+    result: {
+        protocolVersion: string;
+        capabilities: Record<string, unknown>;
+        instructions: string;
+    };
+}
+export interface SyntheticInitRequest {
+    jsonrpc: '2.0';
+    id: number;
+    method: 'initialize';
+    params: Record<string, unknown>;
+}
+/**
+ * Build a JSON-RPC `initialize` *response* frame used when the handshake
+ * detection paths conclude the client sent (or should have sent) initialize
+ * but the SDK never produced a result. The label is appended in parens so
+ * operators can identify which fallback fabricated the frame.
+ */
+export declare function buildForcedInitResultFrame(negotiatedVersion: string, label: 'forced-init-fallback' | 'unconditional-init-fallback', id?: number): ForcedInitFrame;
+/**
+ * Build a synthetic `initialize` *request* used to nudge the SDK request
+ * dispatcher when stdin parsing succeeded but framing failed.
+ */
+export declare function buildSyntheticInitRequest(id?: number): SyntheticInitRequest;

package/dist/server/handshake/fallbackFrames.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Pure JSON-RPC frame builders used by the handshake fallback paths. No I/O,
+ * no mutable state — these can be safely unit tested in isolation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildForcedInitResultFrame = buildForcedInitResultFrame;
+exports.buildSyntheticInitRequest = buildSyntheticInitRequest;
+const BASE_INSTRUCTIONS = 'Use initialize -> tools/list -> tools/call { name, arguments }.';
+/**
+ * Build a JSON-RPC `initialize` *response* frame used when the handshake
+ * detection paths conclude the client sent (or should have sent) initialize
+ * but the SDK never produced a result. The label is appended in parens so
+ * operators can identify which fallback fabricated the frame.
+ */
+function buildForcedInitResultFrame(negotiatedVersion, label, id = 1) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+            protocolVersion: negotiatedVersion,
+            capabilities: {},
+            instructions: `${BASE_INSTRUCTIONS} (${label})`,
+        },
+    };
+}
+/**
+ * Build a synthetic `initialize` *request* used to nudge the SDK request
+ * dispatcher when stdin parsing succeeded but framing failed.
+ */
+function buildSyntheticInitRequest(id = 1) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        method: 'initialize',
+        params: {},
+    };
+}

package/dist/server/handshake/initializeDetector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure detector for the MCP `initialize` JSON-RPC method in a buffered
+ * stdin stream. Handles three increasingly tolerant strategies used by the
+ * legacy stdin sniffer:
+ *
+ *   - direct  : exact `"method":"initialize"` substring match
+ *   - fuzzy   : reconstruct `initialize` near a `"method"` sentinel allowing
+ *               up to 3 character gaps between target letters
+ *   - subseq  : letters-only subsequence match across the whole window
+ *
+ * The detector is intentionally side-effect free; callers own logging.
+ */
+export type InitializeDetectMode = 'direct' | 'fuzzy' | 'subseq';
+export interface InitializeDetectResult {
+    mode: InitializeDetectMode | null;
+}
+/**
+ * Detect an `initialize` request method anywhere in `buffer`.
+ *
+ * @param buffer  raw stdin bytes decoded as utf8
+ * @param fallbackSliceEnabled when true, also probe the trailing 2KB if no
+ *        `"method"` sentinel was found (enables aggressive scanning during
+ *        `INDEX_SERVER_TRACE=healthMixed`)
+ */
+export declare function detectInitializeMethod(buffer: string, fallbackSliceEnabled?: boolean): InitializeDetectResult;
+/**
+ * Extract a numeric `id` from a JSON-RPC frame embedded in `buffer`. Returns
+ * the matched integer or `null` when no plausible id is present. Limited to
+ * 6 digits to match legacy behavior.
+ */
+export declare function extractRequestId(buffer: string): number | null;

package/dist/server/handshake/initializeDetector.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Pure detector for the MCP `initialize` JSON-RPC method in a buffered
+ * stdin stream. Handles three increasingly tolerant strategies used by the
+ * legacy stdin sniffer:
+ *
+ *   - direct  : exact `"method":"initialize"` substring match
+ *   - fuzzy   : reconstruct `initialize` near a `"method"` sentinel allowing
+ *               up to 3 character gaps between target letters
+ *   - subseq  : letters-only subsequence match across the whole window
+ *
+ * The detector is intentionally side-effect free; callers own logging.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectInitializeMethod = detectInitializeMethod;
+exports.extractRequestId = extractRequestId;
+const TARGET = 'initialize';
+const FUZZY_MAX_GAPS = 3;
+const FUZZY_SLICE_LEN = 1200;
+const FALLBACK_SLICE_LEN = 2000;
+function tryFuzzy(slice) {
+    let ti = 0;
+    let gaps = 0;
+    for (let i = 0; i < slice.length && ti < TARGET.length; i++) {
+        const ch = slice[i];
+        if (ch.toLowerCase?.() === TARGET[ti]) {
+            ti++;
+            gaps = 0;
+            continue;
+        }
+        if (gaps < FUZZY_MAX_GAPS) {
+            gaps++;
+            continue;
+        }
+        ti = 0;
+        gaps = 0;
+        if (ch.toLowerCase?.() === TARGET[ti]) {
+            ti++;
+        }
+    }
+    return ti === TARGET.length;
+}
+function trySubseq(buffer) {
+    const letters = buffer.replace(/[^a-zA-Z]/g, '').toLowerCase();
+    let ti = 0;
+    for (let i = 0; i < letters.length && ti < TARGET.length; i++) {
+        if (letters[i] === TARGET[ti])
+            ti++;
+    }
+    return ti === TARGET.length;
+}
+/**
+ * Detect an `initialize` request method anywhere in `buffer`.
+ *
+ * @param buffer  raw stdin bytes decoded as utf8
+ * @param fallbackSliceEnabled when true, also probe the trailing 2KB if no
+ *        `"method"` sentinel was found (enables aggressive scanning during
+ *        `INDEX_SERVER_TRACE=healthMixed`)
+ */
+function detectInitializeMethod(buffer, fallbackSliceEnabled = false) {
+    if (/"method"\s*:\s*"initialize"/.test(buffer)) {
+        return { mode: 'direct' };
+    }
+    const methodIdx = buffer.indexOf('"method"');
+    const sliceA = methodIdx !== -1 ? buffer.slice(methodIdx, methodIdx + FUZZY_SLICE_LEN) : '';
+    const trySlices = sliceA ? [sliceA] : [];
+    if (!sliceA && fallbackSliceEnabled)
+        trySlices.push(buffer.slice(-FALLBACK_SLICE_LEN));
+    for (const slice of trySlices) {
+        if (tryFuzzy(slice))
+            return { mode: 'fuzzy' };
+    }
+    if (trySubseq(buffer))
+        return { mode: 'subseq' };
+    return { mode: null };
+}
+/**
+ * Extract a numeric `id` from a JSON-RPC frame embedded in `buffer`. Returns
+ * the matched integer or `null` when no plausible id is present. Limited to
+ * 6 digits to match legacy behavior.
+ */
+function extractRequestId(buffer) {
+    const m = /"id"\s*:\s*(\d{1,6})/.exec(buffer);
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    return Number.isFinite(n) ? n : null;
+}