fix findings

Author: St0rmz1

CHANGELOG.md

@@ -23,6 +23,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `authToken` is a SecretRef pointing at our own provider — that shape
   is only ever written by `writeStoredToken()` after device auth, so
   the plugin (not the user) owns recovery.
+- `pollDeviceAuth()` now `encodeURIComponent()`s the device-auth code
+  before interpolating it into the poll URL. Defense-in-depth against
+  a compromised or MITM-ed server returning a code with URL meta-chars
+  that would silently redirect polling to a different endpoint.
+- `submitAudit()` now validates that `report.markdown` is a string on
+  the success path. A malformed server response previously surfaced as
+  a confusing `TypeError: Cannot read properties of undefined (reading
+'markdown')`; it now throws a clear
+  "unexpected response shape" error.
+
+### Changed
+
+- Removed the unreachable `{ kind: "pending" }` variant from
+  `DeviceAuthPollResult`. `pollDeviceAuth()` loops internally and only
+  returns terminal states or `timeout`, so the `"pending"` branch in
+  `runShellSecurityFlow` was dead code and confused the contract.
+- Renumbered the ordered list in `src/platform.ts`'s module doc
+  comment. Signals 2–5 are now 1–4.
 
 ## [0.2.0]
 

index.ts

@@ -291,23 +291,14 @@ async function runShellSecurityFlow(
       return "Authentication code expired. Run the security checkup again to get a fresh code.";
     }
 
-    if (pollResult.kind === "timeout") {
-      // Our local poll deadline was hit while the server was still
-      // returning pending. The code may still be valid server-side.
-      // Leave the pending code in place so the next invocation picks up
-      // where we left off, and tell the user to retry once they've
-      // approved in the browser.
-      return (
-        "Still waiting for you to approve in the browser.\n\n" +
-        "Once you've approved, run the security checkup again and we'll pick up where we left off."
-      );
-    }
-    // pollResult.kind === "pending" (shouldn't reach here: pollDeviceAuth
-    // loops internally until a terminal state or timeout). Fall through
-    // to treat as timeout for safety.
+    // pollResult.kind === "timeout": our local poll deadline was hit
+    // while the server was still returning pending. The code may still
+    // be valid server-side. Leave the pending code in place so the
+    // next invocation picks up where we left off, and tell the user
+    // to retry once they've approved in the browser.
     return (
       "Still waiting for you to approve in the browser.\n\n" +
-      "Once you've approved, run the security checkup again."
+      "Once you've approved, run the security checkup again and we'll pick up where we left off."
     );
   }
 

src/auth/device-auth.ts

@@ -50,10 +50,13 @@ export type DeviceAuthStartResult = {
  *             was still returning pending. The code may still be valid
  *             server-side; caller should NOT clear pending code so the
  *             next invocation can keep polling.
+ *
+ * `pending` is intentionally NOT in this union. `pollDeviceAuth()` loops
+ * internally and never returns the transient pending state — it only
+ * returns a terminal outcome or `timeout`.
  */
 export type DeviceAuthPollResult =
   | { kind: "approved"; token: string }
-  | { kind: "pending" }
   | { kind: "denied" }
   | { kind: "expired" }
   | { kind: "timeout" };
@@ -112,7 +115,11 @@ export async function pollDeviceAuth(
   logger?: PluginLogger,
 ): Promise<DeviceAuthPollResult> {
   const fetchFn: typeof fetch = resolveFetch() ?? globalThis.fetch;
-  const pollUrl = `${apiBase}/api/device-auth/codes/${code}`;
+  // Defense-in-depth: the code is a server-issued opaque string, but if
+  // the server ever returned one containing `/` or other URL meta-chars
+  // an unencoded concat would silently redirect the poll to a different
+  // endpoint under the same origin.
+  const pollUrl = `${apiBase}/api/device-auth/codes/${encodeURIComponent(code)}`;
   const deadline = Date.now() + POLL_TIMEOUT_MS;
 
   while (Date.now() < deadline) {

src/client.ts

@@ -106,5 +106,16 @@ export async function submitAudit(
     );
   }
 
-  return (await resp.json()) as AnalyzeResponse;
+  const body = (await resp.json()) as AnalyzeResponse;
+  // Guard against an unexpected success shape (e.g. a partial rollout
+  // or a proxy rewriting the response). Without this, a missing
+  // `report.markdown` surfaces as a confusing
+  // `TypeError: Cannot read properties of undefined (reading 'markdown')`
+  // from the caller; this message is actionable.
+  if (typeof body?.report?.markdown !== "string") {
+    throw new Error(
+      "KiloCode analysis API returned an unexpected response shape.",
+    );
+  }
+  return body;
 }

src/platform.ts

@@ -13,15 +13,15 @@
  * circuits to "kiloclaw".
  *
  * Ordering (stopping at the first hit):
- *   2. openclaw.json has `plugins.entries["kiloclaw-customizer"].enabled`
+ *   1. openclaw.json has `plugins.entries["kiloclaw-customizer"].enabled`
  *      truthy — the kiloclaw controller writes this at boot for every
  *      kiloclaw instance, predating any of the env-var signals. Most
  *      durable universal signal today.
- *   3. openclaw.json `plugins.load.paths` contains the kiloclaw
+ *   2. openclaw.json `plugins.load.paths` contains the kiloclaw
  *      customizer install path — same writer, redundant cross-check.
- *   4. `process.env.KILOCLAW_SANDBOX_ID` is set — present on every
+ *   3. `process.env.KILOCLAW_SANDBOX_ID` is set — present on every
  *      kiloclaw instance since 2026-03-22.
- *   5. `process.env.KILOCODE_FEATURE === "kiloclaw"` — the original
+ *   4. `process.env.KILOCODE_FEATURE === "kiloclaw"` — the original
  *      env-var signal, present on kiloclaw since 2026-02-17.
  *
  * We intentionally do NOT add a loose `KILOCLAW_*`-prefix heuristic;