deepadb 1.1.1 → 1.1.3

package/build/middleware/cleanup.js

@@ -1,20 +1,53 @@
+// Copyright 2026 Jason <fullread@github>
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Process Cleanup Registry — Centralized signal handler for child process cleanup.
  *
- * Multiple modules (logcat-watch, ril-intercept, mirroring) spawn long-running
- * child processes that must be killed on server exit. Instead of each module
- * independently registering SIGINT/SIGTERM/exit handlers (which creates
- * ordering dependencies and redundant process.exit() calls), all modules
- * register their cleanup functions here.
+ * Multiple modules (logcat-watch, ril-intercept, mirroring, emulator, qemu)
+ * spawn long-running child processes that must be killed on server exit.
+ * Instead of each module independently registering SIGINT/SIGTERM/exit
+ * handlers (which creates ordering dependencies and redundant
+ * process.exit() calls), all modules register their cleanup functions here.
  *
  * One set of signal handlers runs all registered cleanups in order.
+ *
+ * Cleanup functions may return a Promise; the SIGINT/SIGTERM handlers
+ * await them. The synchronous 'exit' handler is best-effort — it fires
+ * the cleanups but cannot wait for async work to complete.
  */
 const registry = new Map();
 let registered = false;
-function runAllCleanups() {
-    for (const [, fn] of registry) {
+async function runAllCleanups() {
+    for (const [key, fn] of registry) {
+        try {
+            await fn();
+        }
+        catch (err) {
+            // K7 fix: log the failing cleanup's key + error to stderr so
+            // operators can diagnose process-zombification (the previous
+            // empty catch made this invisible).
+            const detail = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[cleanup] "${key}" failed: ${detail}\n`);
+        }
+    }
+}
+let warnedAsyncOnExit = false;
+function runAllCleanupsSync() {
+    // Used by the 'exit' event handler, which cannot await. Async cleanups
+    // are still invoked but their promises are discarded — best-effort.
+    // K4 fix: log a one-shot stderr warning the first time we discard an
+    // async cleanup so developers see "this cleanup may be cut short on
+    // abnormal exit; for guaranteed completion route shutdown through
+    // SIGINT or SIGTERM."
+    for (const [key, fn] of registry) {
         try {
-            fn();
+            const ret = fn();
+            if (ret && typeof ret.then === "function") {
+                if (!warnedAsyncOnExit) {
+                    warnedAsyncOnExit = true;
+                    process.stderr.write(`[cleanup] async cleanup "${key}" invoked from 'exit' handler — promise discarded. Async work may be cut short on abnormal exit; SIGINT/SIGTERM awaits all cleanups.\n`);
+                }
+            }
         }
         catch {
             // Cleanup must not throw during shutdown
@@ -25,20 +58,50 @@ function ensureHandlers() {
     if (registered)
         return;
     registered = true;
-    process.on("exit", runAllCleanups);
-    process.on("SIGINT", () => {
-        runAllCleanups();
-        process.exit(0);
+    process.on("exit", runAllCleanupsSync);
+    // K3 fix: SIGINT/SIGTERM handlers exit with the conventional Unix
+    // signal-based code (128 + signum) instead of always 0, so wrapper
+    // scripts checking $? can distinguish "completed normally" from
+    // "interrupted by user".
+    //   SIGINT  = signum 2  → exit 130
+    //   SIGTERM = signum 15 → exit 143
+    process.on("SIGINT", async () => {
+        await runAllCleanups();
+        process.exit(130);
+    });
+    process.on("SIGTERM", async () => {
+        await runAllCleanups();
+        process.exit(143);
+    });
+    // K1 fix: cover additional shutdown paths that previously leaked child
+    // processes — SIGHUP (terminal disconnect), SIGBREAK (Windows Ctrl+Break),
+    // and catastrophic JS errors (uncaughtException, unhandledRejection).
+    // Without these, closing a parent terminal without Ctrl+C left orphan
+    // emulator/scrcpy/logcat children. Process.on for unsupported signals on
+    // a given platform is a no-op, so this is safe cross-platform.
+    process.on("SIGHUP", async () => {
+        await runAllCleanups();
+        process.exit(129); // 128 + SIGHUP(1)
     });
-    process.on("SIGTERM", () => {
-        runAllCleanups();
-        process.exit(0);
+    process.on("SIGBREAK", async () => {
+        await runAllCleanups();
+        process.exit(149); // 128 + SIGBREAK(21) on Windows
+    });
+    process.on("uncaughtException", async (err) => {
+        process.stderr.write(`[cleanup] uncaughtException: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+        await runAllCleanups();
+        process.exit(1);
+    });
+    process.on("unhandledRejection", async (reason) => {
+        process.stderr.write(`[cleanup] unhandledRejection: ${reason instanceof Error ? reason.stack ?? reason.message : String(reason)}\n`);
+        await runAllCleanups();
+        process.exit(1);
     });
 }
 /**
  * Register a cleanup function that will be called on process exit/SIGINT/SIGTERM.
  * Each module should register under a unique key. Re-registering the same key
- * replaces the previous function.
+ * replaces the previous function. The function may return a Promise.
  */
 export function registerCleanup(key, fn) {
     ensureHandlers();
@@ -50,4 +113,73 @@ export function registerCleanup(key, fn) {
 export function unregisterCleanup(key) {
     registry.delete(key);
 }
+/**
+ * Kill a child process with two-stage SIGTERM → SIGKILL fallback.
+ *
+ * Sends SIGTERM, waits up to `graceMs` for the child to exit voluntarily,
+ * then escalates to SIGKILL if it's still running. Resolves when the
+ * child has exited OR after the SIGKILL has been sent.
+ *
+ * This closes audit findings AC3 (emulator) and AK8 (mirroring) — and
+ * matches the same hazard in logcat-watch.ts and ril-intercept.ts where
+ * a bare `proc.kill()` could leave a hung child orphaned if it ignored
+ * SIGTERM (common with mid-snapshot Android emulators, hung video pipes
+ * in scrcpy, and stuck logcat readers on a wedged device).
+ *
+ * Default `graceMs` = 1500: enough for a healthy child to clean up,
+ * short enough that shutdown stays responsive.
+ *
+ * Safe to call on an already-exited child (no-op). Safe to call from
+ * SIGINT/SIGTERM contexts via async cleanups registered with
+ * `registerCleanup` — the registry awaits each cleanup before exiting.
+ */
+export async function gracefulKill(child, graceMs = 1500) {
+    // No-op if already dead or never started.
+    if (!child.pid || child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    // Stage 1: Send SIGTERM.
+    try {
+        child.kill("SIGTERM");
+    }
+    catch {
+        // Child may have died between the check and the kill — treat as success.
+        return;
+    }
+    // Wait for the child to exit, OR for graceMs to elapse.
+    const exited = await new Promise((resolve) => {
+        let resolved = false;
+        const finish = (didExit) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            child.off("exit", onExit);
+            resolve(didExit);
+        };
+        const onExit = () => finish(true);
+        const timer = setTimeout(() => finish(false), graceMs);
+        child.once("exit", onExit);
+    });
+    // Stage 2: If still alive, escalate to SIGKILL.
+    if (!exited) {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            // Child raced us — already dead.
+        }
+    }
+}
+/**
+ * Convenience: gracefully kill multiple children in parallel.
+ * All children get SIGTERM concurrently; each gets SIGKILL after graceMs
+ * if still running. Resolves when all have settled.
+ */
+export async function gracefulKillAll(children, graceMs = 1500) {
+    const tasks = [];
+    for (const c of children)
+        tasks.push(gracefulKill(c, graceMs));
+    await Promise.all(tasks);
+}
 //# sourceMappingURL=cleanup.js.map

package/build/middleware/cleanup.js.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../src/middleware/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,QAAQ,GAA2B,IAAI,GAAG,EAAE,CAAC;AACnD,IAAI,UAAU,GAAG,KAAK,CAAC;AAEvB,SAAS,cAAc;IACrB,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,EAAE,EAAE,CAAC;QACP,CAAC;QAAC,MAAM,CAAC;YACP,yCAAyC;QAC3C,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,cAAc;IACrB,IAAI,UAAU;QAAE,OAAO;IACvB,UAAU,GAAG,IAAI,CAAC;IAElB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,cAAc,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,cAAc,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,EAAa;IACxD,cAAc,EAAE,CAAC;IACjB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC"}
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../src/middleware/cleanup.ts"],"names":[],"mappings":"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"}

package/build/middleware/fetch-utils.d.ts

@@ -1,19 +1,62 @@
 /**
- * Fetch Utilities — Shared HTTP helpers with response size limits.
+ * Fetch Utilities — Shared HTTP helpers with protocol, timeout, redirect, and size limits.
  *
- * Used by the plugin registry, workflow marketplace, and any module
- * that fetches external resources. Enforces a maximum response body
- * size to prevent memory exhaustion from oversized or malicious responses.
+ * Used by the plugin registry, workflow marketplace, and any module that
+ * fetches external resources. Layered defenses against malicious or
+ * misconfigured external sources:
+ *   - Protocol allowlist: https:// only (no http://, data:, file://, etc.).
+ *     Validated on the INITIAL url AND on every redirect target. Defends
+ *     against SSRF (file://, http://internal.rfc1918), plaintext credential
+ *     leak (http://), and content injection via local-file or inline-data URLs.
+ *   - Manual redirect handling: redirects are NOT auto-followed by the
+ *     underlying fetch — we follow them ourselves with per-hop protocol
+ *     re-validation and a 5-hop cap. Defends against a compromised or
+ *     hijacked initial endpoint that 302-redirects to http://attacker.com
+ *     or file:///etc/passwd, which the default `redirect: "follow"` would
+ *     traverse silently and bypass the initial protocol check.
+ *   - Request timeout: 30 seconds via AbortSignal.timeout() — shared across
+ *     redirect hops, header arrival, AND body read. Total operation is
+ *     bounded by one 30s window, not 30s × hops. Defends against slow-loris
+ *     servers and slow-drip redirect chains.
+ *   - Response size cap: 5 MB streaming check. Defends against memory
+ *     exhaustion from oversized or pathological responses, even when the
+ *     server omits Content-Length.
+ *
+ * Tests that need to exercise post-fetch parsing logic should mock
+ * fetchText/fetchJson at the function level rather than feeding non-https
+ * URLs through the real fetcher. Redirect-following behavior is validated
+ * during manual audit at release prep (per the test-supply-chain.mjs convention).
+ */
+/**
+ * Throw if the URL does not begin with `https://`. Applied to the initial
+ * URL and re-applied to every redirect target so a `Location: http://...`
+ * header cannot bypass the protocol allowlist.
+ *
+ * Exported for unit testing.
  */
+/**
+ * H1 note: case-sensitivity is INTENTIONAL. RFC 3986 says scheme is
+ * case-insensitive, so technically `HTTPS://example.com` is valid. But
+ * any URL produced by a real client library normalizes to lowercase, so
+ * an uppercase scheme in practice signals either (a) a hand-typed URL by
+ * an operator (the strict check catches typos), or (b) an adversarial
+ * input trying to bypass an allowlist check by using a non-canonical
+ * form. Strict-lowercase is the safer choice for an allowlist gate.
+ */
+export declare function requireHttps(url: string, context: string): void;
 /**
  * Fetch a URL and parse the response as JSON.
- * Enforces a response size limit to prevent memory exhaustion.
+ * Enforces protocol, timeout, redirect, and size limits via fetchText().
  */
 export declare function fetchJson(url: string): Promise<unknown>;
 /**
  * Fetch a URL and return the response body as text.
- * Enforces a response size limit via streaming to prevent memory exhaustion,
- * even when the server omits the Content-Length header.
+ *
+ * Enforces:
+ *   - https:// protocol on the INITIAL url AND every redirect target
+ *   - At most 5 redirect hops (fail-closed beyond)
+ *   - 30s total timeout via shared AbortSignal (covers hops + body read)
+ *   - 5 MB body size cap via streaming size check
  */
 export declare function fetchText(url: string): Promise<string>;
 //# sourceMappingURL=fetch-utils.d.ts.map

package/build/middleware/fetch-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-utils.d.ts","sourceRoot":"","sources":["../../src/middleware/fetch-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;GAGG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG7D;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2C5D"}
+{"version":3,"file":"fetch-utils.d.ts","sourceRoot":"","sources":["../../src/middleware/fetch-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAcH;;;;;;GAMG;AACH;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAM/D;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAY7D;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoG5D"}

package/build/middleware/fetch-utils.js

@@ -1,37 +1,143 @@
+// Copyright 2026 Jason <fullread@github>
+// SPDX-License-Identifier: Apache-2.0
 /**
- * Fetch Utilities — Shared HTTP helpers with response size limits.
+ * Fetch Utilities — Shared HTTP helpers with protocol, timeout, redirect, and size limits.
  *
- * Used by the plugin registry, workflow marketplace, and any module
- * that fetches external resources. Enforces a maximum response body
- * size to prevent memory exhaustion from oversized or malicious responses.
+ * Used by the plugin registry, workflow marketplace, and any module that
+ * fetches external resources. Layered defenses against malicious or
+ * misconfigured external sources:
+ *   - Protocol allowlist: https:// only (no http://, data:, file://, etc.).
+ *     Validated on the INITIAL url AND on every redirect target. Defends
+ *     against SSRF (file://, http://internal.rfc1918), plaintext credential
+ *     leak (http://), and content injection via local-file or inline-data URLs.
+ *   - Manual redirect handling: redirects are NOT auto-followed by the
+ *     underlying fetch — we follow them ourselves with per-hop protocol
+ *     re-validation and a 5-hop cap. Defends against a compromised or
+ *     hijacked initial endpoint that 302-redirects to http://attacker.com
+ *     or file:///etc/passwd, which the default `redirect: "follow"` would
+ *     traverse silently and bypass the initial protocol check.
+ *   - Request timeout: 30 seconds via AbortSignal.timeout() — shared across
+ *     redirect hops, header arrival, AND body read. Total operation is
+ *     bounded by one 30s window, not 30s × hops. Defends against slow-loris
+ *     servers and slow-drip redirect chains.
+ *   - Response size cap: 5 MB streaming check. Defends against memory
+ *     exhaustion from oversized or pathological responses, even when the
+ *     server omits Content-Length.
+ *
+ * Tests that need to exercise post-fetch parsing logic should mock
+ * fetchText/fetchJson at the function level rather than feeding non-https
+ * URLs through the real fetcher. Redirect-following behavior is validated
+ * during manual audit at release prep (per the test-supply-chain.mjs convention).
  */
 /** Maximum response body size in bytes (5 MB). */
 const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+/** Maximum time to wait for the entire fetch operation, in milliseconds (30 seconds).
+ *  Covers initial request, all redirect hops, header arrival, and body read. */
+const FETCH_TIMEOUT_MS = 30_000;
+/** Maximum number of redirect hops to follow before failing closed.
+ *  Matches the typical 5-hop limits in browsers (curl defaults to 50,
+ *  but for a supply-chain fetch we want tight bounds). */
+const MAX_REDIRECTS = 5;
+/**
+ * Throw if the URL does not begin with `https://`. Applied to the initial
+ * URL and re-applied to every redirect target so a `Location: http://...`
+ * header cannot bypass the protocol allowlist.
+ *
+ * Exported for unit testing.
+ */
+/**
+ * H1 note: case-sensitivity is INTENTIONAL. RFC 3986 says scheme is
+ * case-insensitive, so technically `HTTPS://example.com` is valid. But
+ * any URL produced by a real client library normalizes to lowercase, so
+ * an uppercase scheme in practice signals either (a) a hand-typed URL by
+ * an operator (the strict check catches typos), or (b) an adversarial
+ * input trying to bypass an allowlist check by using a non-canonical
+ * form. Strict-lowercase is the safer choice for an allowlist gate.
+ */
+export function requireHttps(url, context) {
+    if (!url.startsWith("https://")) {
+        throw new Error(`Refusing to fetch non-https URL: ${url} (${context}). Only https:// URLs are permitted.`);
+    }
+}
 /**
  * Fetch a URL and parse the response as JSON.
- * Enforces a response size limit to prevent memory exhaustion.
+ * Enforces protocol, timeout, redirect, and size limits via fetchText().
  */
 export async function fetchJson(url) {
     const text = await fetchText(url);
-    return JSON.parse(text);
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        // H2 fix: wrap JSON parse errors with the URL context so a misconfigured
+        // registry returning an HTML error page produces "Invalid JSON from
+        // https://... — Unexpected token <" instead of a bare parse error with
+        // no indication of which fetch failed.
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid JSON from ${url} — ${detail}`, { cause: err });
+    }
 }
 /**
  * Fetch a URL and return the response body as text.
- * Enforces a response size limit via streaming to prevent memory exhaustion,
- * even when the server omits the Content-Length header.
+ *
+ * Enforces:
+ *   - https:// protocol on the INITIAL url AND every redirect target
+ *   - At most 5 redirect hops (fail-closed beyond)
+ *   - 30s total timeout via shared AbortSignal (covers hops + body read)
+ *   - 5 MB body size cap via streaming size check
  */
 export async function fetchText(url) {
-    const response = await fetch(url);
+    requireHttps(url, "initial URL");
+    // Share one AbortSignal across all redirect hops, header arrival, and body
+    // read. The 30s budget is for the entire operation — a chain of slow-drip
+    // redirects cannot stack up to 30s × hops.
+    const signal = AbortSignal.timeout(FETCH_TIMEOUT_MS);
+    // Manual redirect handling so we can re-validate the protocol of every
+    // hop. The default `redirect: "follow"` would silently traverse a
+    // https→http or https→file redirect from a compromised initial endpoint,
+    // defeating the protocol allowlist entirely.
+    let currentUrl = url;
+    let response = null;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        const r = await fetch(currentUrl, { signal, redirect: "manual" });
+        // 304 Not Modified is a 3xx that is NOT a redirect — treat as terminal.
+        if (r.status >= 300 && r.status < 400 && r.status !== 304) {
+            const location = r.headers.get("location");
+            if (!location) {
+                // 3xx without Location is unusual but possible (e.g., 305 Use Proxy
+                // without a Location header). Treat as a terminal response so the
+                // caller sees the raw status.
+                response = r;
+                break;
+            }
+            // Drain the redirect response body to free the connection eagerly.
+            r.body?.cancel().catch(() => { });
+            if (hop === MAX_REDIRECTS) {
+                throw new Error(`Too many redirects (max ${MAX_REDIRECTS}) starting from ${url}`);
+            }
+            // Resolve relative URLs against the current URL, then re-validate.
+            currentUrl = new URL(location, currentUrl).href;
+            requireHttps(currentUrl, `redirect hop ${hop + 1} from ${url}`);
+            continue;
+        }
+        response = r;
+        break;
+    }
+    if (!response) {
+        // Unreachable in practice — the loop either sets response or throws.
+        throw new Error(`Failed to fetch ${url}: no response obtained`);
+    }
     if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText} — ${url}`);
+        throw new Error(`HTTP ${response.status}: ${response.statusText} — ${currentUrl}`);
     }
-    // Fast-reject via Content-Length header if available
+    // Fast-reject via Content-Length header if available.
     const contentLength = response.headers.get("content-length");
     if (contentLength && parseInt(contentLength, 10) > MAX_RESPONSE_BYTES) {
         throw new Error(`Response too large: ${contentLength} bytes (max ${MAX_RESPONSE_BYTES})`);
     }
-    // Stream-read the body with incremental size checking.
-    // This prevents memory exhaustion even when Content-Length is absent.
+    // Stream-read the body with incremental size checking. The AbortSignal
+    // attached to fetch above also applies to body reads, so a slow-drip server
+    // will trip the 30s timeout here rather than hanging until MAX_RESPONSE_BYTES.
     if (response.body) {
         const reader = response.body.getReader();
         const chunks = [];
@@ -54,7 +160,14 @@ export async function fetchText(url) {
         }
         return new TextDecoder().decode(Buffer.concat(chunks));
     }
-    // Fallback for environments where response.body is null
+    // Fallback for environments where response.body is null (extremely rare
+    // in modern Node). H4 audit note: the function-level Content-Length
+    // pre-check at the top of this function already rejects declared-oversize
+    // bodies BEFORE we get here. The remaining unguarded case is a chunked
+    // response with no Content-Length AND null response.body — buffer below
+    // and post-read length check is the best we can do without a streaming
+    // body. Accept the unbounded read for this rare path; the post-check
+    // still catches the result.
     const text = await response.text();
     if (text.length > MAX_RESPONSE_BYTES) {
         throw new Error(`Response body too large: ${text.length} characters (max ${MAX_RESPONSE_BYTES})`);

package/build/middleware/fetch-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-utils.js","sourceRoot":"","sources":["../../src/middleware/fetch-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kDAAkD;AAClD,MAAM,kBAAkB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,UAAU,MAAM,GAAG,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,qDAAqD;IACrD,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC7D,IAAI,aAAa,IAAI,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC,GAAG,kBAAkB,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,uBAAuB,aAAa,eAAe,kBAAkB,GAAG,CAAC,CAAC;IAC5F,CAAC;IAED,uDAAuD;IACvD,sEAAsE;IACtE,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QACzC,MAAM,MAAM,GAAiB,EAAE,CAAC;QAChC,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,IAAI,CAAC;YACH,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC5C,IAAI,IAAI;oBAAE,MAAM;gBAChB,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC;gBAC3B,IAAI,UAAU,GAAG,kBAAkB,EAAE,CAAC;oBACpC,MAAM,CAAC,MAAM,EAAE,CAAC;oBAChB,MAAM,IAAI,KAAK,CAAC,qCAAqC,kBAAkB,uBAAuB,CAAC,CAAC;gBAClG,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,CAAC;QAED,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,wDAAwD;IACxD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,CAAC,MAAM,oBAAoB,kBAAkB,GAAG,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"fetch-utils.js","sourceRoot":"","sources":["../../src/middleware/fetch-utils.ts"],"names":[],"mappings":"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"}

package/build/middleware/fs-utils.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Filesystem Utilities - Shared helpers for safe on-disk state.
+ *
+ * Four primitives used across DeepADB tempDir-backed storage:
+ *
+ *   1. ensurePrivateDir(path) - Create a directory with restrictive
+ *      permissions (0o700 on Unix; mode bits ignored on Windows). Use
+ *      everywhere we create a subdirectory under tempDir. Defends against
+ *      other-user reads on shared Unix hosts.
+ *
+ *   2. writeAtomicSync(path, data) - Write via a unique-per-call .tmp
+ *      path then atomic rename. Defends against (a) mid-write crashes
+ *      leaving corrupt data on disk, (b) concurrent readers seeing a
+ *      partially-written file, (c) concurrent writers to the same path
+ *      racing on .tmp filenames.
+ *
+ *   3. sanitizeFilenameComponent(name, maxLen?) - Replace any character
+ *      outside [a-zA-Z0-9_-] with underscore. Optional maxLen truncates
+ *      the result. Empty results are coerced to "_" so the caller never
+ *      receives a zero-length component. Centralizes the pattern used
+ *      across several tool modules for user-supplied identifier strings.
+ *
+ *   4. sanitizeFilenameComponentDotted(name, maxLen?) - Like (3) but
+ *      ALSO allows "." in the output (for package names like
+ *      "com.example.app"). Defangs pure-dot strings (".", "..", "...")
+ *      by coercing them to "_", so a caller using the result directly
+ *      as a path component cannot be steered into parent-directory
+ *      traversal by an adversarial input.
+ *
+ * Note on existing directories: ensurePrivateDir only sets mode on
+ * directories it CREATES. Directories that already exist (from older
+ * DeepADB versions) keep their existing permissions. To remediate, the
+ * operator can chmod 700 the affected directories manually, or just
+ * delete them so they are recreated with the new mode.
+ */
+/** Create directory with owner-only permissions. Idempotent. */
+export declare function ensurePrivateDir(path: string): void;
+/** Atomic write: unique .tmp + rename. Throws on failure (caller handles). */
+export declare function writeAtomicSync(path: string, data: string | Buffer): void;
+/**
+ * Sanitize a string for use as a filename component. Replaces every
+ * character outside [a-zA-Z0-9_-] with "_".
+ *
+ * Safe against path traversal because `.`, `/`, and `\\` are all outside
+ * the allowlist (they become `_`). For cases where rejection is preferable
+ * to silent replacement, validate the raw input against /^[a-zA-Z0-9_-]+$/
+ * before calling tools.
+ *
+ * @param name  Raw user-supplied identifier.
+ * @param maxLen Optional length cap applied after sanitization. Callers
+ *               that build long paths (Windows MAX_PATH-sensitive) should
+ *               always pass this.
+ * @returns Sanitized string, guaranteed non-empty (empty input collapses
+ *          to "_" so callers never receive a zero-length component).
+ */
+export declare function sanitizeFilenameComponent(name: string, maxLen?: number): string;
+/**
+ * Like sanitizeFilenameComponent but ALSO allows "." in the output.
+ * Intended for Android-style package identifiers ("com.example.app") and
+ * similar dotted names where stripping dots would damage the identifier.
+ *
+ * Pure-dot strings (".", "..", "...", etc.) are coerced to "_" so a
+ * caller that uses the result directly as a path component cannot be
+ * steered into parent-directory traversal by an adversarial input.
+ *
+ * @param name  Raw user-supplied dotted identifier (e.g., package name).
+ * @param maxLen Optional length cap applied after sanitization.
+ * @returns Sanitized string, guaranteed non-empty AND not a pure-dot
+ *          traversal sequence.
+ */
+/**
+ * A8 note: a LEADING dot is preserved (only character-class filtering
+ * applies — the dot is in the allowed set). On Unix, a result like
+ * `.hidden` becomes an actual hidden file in the result-handle store and
+ * other directory listings. This is intentional under the design (callers
+ * who want to allow package names like com.example.app need the dot), but
+ * means operators browsing the temp directory should pass `ls -A` not
+ * bare `ls` to see all entries. If a future caller wants the no-leading-
+ * dot behavior, it should sanitize the input before calling this helper.
+ */
+export declare function sanitizeFilenameComponentDotted(name: string, maxLen?: number): string;
+/**
+ * Returns true iff `candidatePath`, after path resolution, is contained
+ * within `dir` — either equal to `dir` or strictly underneath it.
+ *
+ * Containment uses a path-separator boundary check, NOT a string prefix.
+ * Without the boundary, `candidatePath = /parent/tempDir_evil/x` would
+ * pass containment against `dir = /parent/tempDir` because the absolute
+ * path string-prefix-matches — even though the two are sibling directories.
+ *
+ * Both POSIX `/` and Windows `\\` separators are recognized so a candidate
+ * resolved on either platform is handled correctly.
+ *
+ * Usage:
+ *   if (!isWithinDir(userOutputDir, ctx.config.tempDir)) {
+ *     throw new Error("Output directory must be inside tempDir");
+ *   }
+ *
+ * This is the centralized successor to the inline pattern that previously
+ * lived in tools/qemu.ts (verifyContainment, correctly using a separator
+ * boundary) and tools/split-apk.ts / tools/registry.ts (which used a bare
+ * string-prefix check and were vulnerable to the sibling-directory bypass).
+ * Lifting to shared middleware fixes the bypass at both call sites.
+ */
+export declare function isWithinDir(candidatePath: string, dir: string): boolean;
+/**
+ * Read and JSON-parse a file. On any failure (missing, unreadable, malformed),
+ * log a warning via the supplied logger and return null. Used by tools that
+ * walk a directory of JSON files (fingerprints, baselines, marketplace
+ * workflows, plugin metadata) and want to skip-but-surface corruption rather
+ * than abort the whole walk OR silently drop the entry.
+ *
+ * Closes audit findings AE8 / AO6 / AU6 / BJ7 / BN7 — the recurring silent
+ * `} catch { /* skip corrupt * / }` pattern. Surfaces corruption to the
+ * operator so a quietly-shrinking handle count doesn't go unnoticed.
+ *
+ * The logger is optional so this is safe to call from contexts without a
+ * Logger in scope (some loadFingerprints / listing functions don't take a
+ * ToolContext). When absent, the warning goes to stderr — non-silent.
+ *
+ * Returns null on any failure; caller should skip the entry.
+ */
+export declare function tryReadJsonOrWarn<T = unknown>(filePath: string, context: string, logger?: {
+    warn: (msg: string) => void;
+}): T | null;
+//# sourceMappingURL=fs-utils.d.ts.map

package/build/middleware/fs-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-utils.d.ts","sourceRoot":"","sources":["../../src/middleware/fs-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4BzE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAW/E;AAED;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBrF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAcvE;AACD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAC3C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACvC,CAAC,GAAG,IAAI,CAUV"}