@theplato/tiro-cli 0.3.0 → 0.4.0

package/AGENTS.md

@@ -88,3 +88,27 @@ Two ways to authenticate:
 
 The CLI never prints tokens to stdout. `tiro auth status` shows only the
 first 4 characters of the access token.
+
+## Security regression suite (pre-deploy contract)
+
+Every release MUST keep `npm run test:security` green. The suite pins the
+following defenses; if any test breaks, the corresponding attack surface
+has reopened — do not publish.
+
+| ID | Surface | What the test guards |
+|---|---|---|
+| **C1** | `lib/config.ts` `validateHostname` | Rejects non-https/non-loopback hostnames so `TIRO_HOSTNAME` / `--hostname` cannot redirect OAuth + API traffic to an attacker. |
+| **H1** | `lib/auth/pkce.ts` `verifyState` | Constant-time OAuth state CSRF compare. |
+| **H2** | `lib/auth/loopback.ts` | OAuth redirect listener is GET-only, single-shot, `Connection: close` — local processes can't race or replay a callback. |
+| **H3** | `lib/api/client.ts` `buildApiUrl` | API path must be relative to the configured hostname — refuses absolute / protocol-relative input that would leak the bearer token. |
+| **H4** | `lib/config.ts` `getOauthClientId` | DCR `client_id` cache is bound to the hostname it was registered against; a swapped hostname misses the cache. |
+| **M1** | `lib/output/file.ts` `assertSafeOutputPath` | `--output` rejects `..` segments unless `--force`; an agent forwarding untrusted input cannot escape its scope. |
+| **M2** | `lib/auth/token.ts` `decodeJwtPayload` | Documented as display-only — claims must never gate auth, scope, identity, or expiry decisions. |
+
+Pre-deploy checklist:
+
+1. `npm run typecheck`
+2. `npm run test:security` (regression gate)
+3. `npm test` (full suite)
+4. `npm run build`
+5. Smoke: `node dist/bin/tiro.js auth status`

package/dist/bin/tiro.js

@@ -140,7 +140,7 @@ import "commander";
 import { z } from "zod";
 
 // src/lib/auth/pkce.ts
-import { createHash, randomBytes } from "crypto";
+import { createHash, randomBytes, timingSafeEqual } from "crypto";
 function generatePkce() {
   const codeVerifier = base64url(randomBytes(32));
   const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
@@ -149,6 +149,12 @@ function generatePkce() {
 function generateState() {
   return base64url(randomBytes(24));
 }
+function verifyState(received, expected) {
+  const a = Buffer.from(received, "utf8");
+  const b = Buffer.from(expected, "utf8");
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
 function base64url(buf) {
   return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
@@ -168,21 +174,33 @@ async function startLoopbackServer() {
     pendingReject = null;
     fn(arg);
   };
+  let consumed = false;
   const server = http.createServer((req, res) => {
+    res.setHeader("Connection", "close");
+    res.setHeader("Cache-Control", "no-store");
     if (!req.url) {
       res.writeHead(400).end();
       return;
     }
+    if (req.method !== "GET") {
+      res.writeHead(405, { "Content-Type": "text/plain", Allow: "GET" }).end("Method not allowed");
+      return;
+    }
     const url = new URL(req.url, `http://127.0.0.1`);
     if (url.pathname !== "/callback") {
       res.writeHead(404, { "Content-Type": "text/plain" }).end("Not found");
       return;
     }
+    if (consumed) {
+      res.writeHead(410, { "Content-Type": "text/plain" }).end("Callback already consumed");
+      return;
+    }
     const code = url.searchParams.get("code");
     const state = url.searchParams.get("state");
     const error = url.searchParams.get("error");
     const errorDesc = url.searchParams.get("error_description") ?? "";
     if (error) {
+      consumed = true;
       const detail = errorDesc ? ` \u2014 ${errorDesc}` : "";
       respondError(res, 500, `OAuth error: ${error}${detail}`);
       if (pendingReject) settle(pendingReject, new Error(`OAuth error: ${error}${detail}`));
@@ -193,6 +211,7 @@ async function startLoopbackServer() {
       if (pendingReject) settle(pendingReject, new Error("Missing code or state"));
       return;
     }
+    consumed = true;
     respondSuccess(res);
     if (pendingResolve) settle(pendingResolve, { code, state });
   });
@@ -434,36 +453,90 @@ function decodeJwtPayload(token) {
 // src/lib/config.ts
 import Conf from "conf";
 var DEFAULT_HOSTNAME = "https://api.tiro.ooo";
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
 var config = new Conf({
   projectName: "tiro",
   defaults: {
     hostname: DEFAULT_HOSTNAME,
     oauthClientId: null,
     oauthClientIdRegisteredAt: null,
+    oauthClientHostname: null,
     defaultOutputDir: null
   }
 });
+function validateHostname(input) {
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw hostnameError("empty hostname", input);
+  }
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw hostnameError("not a valid URL", input);
+  }
+  if (url.protocol === "https:") {
+  } else if (url.protocol === "http:" && isLoopback(url.hostname)) {
+  } else {
+    throw hostnameError(
+      `disallowed scheme "${url.protocol}" \u2014 only https:// or http://localhost is permitted`,
+      input
+    );
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw hostnameError("URL must not embed credentials", input);
+  }
+  if (url.search !== "" || url.hash !== "") {
+    throw hostnameError("URL must not include query or fragment", input);
+  }
+  if (url.pathname !== "" && url.pathname !== "/") {
+    throw hostnameError("URL must be host root (no path segment)", input);
+  }
+  const origin = url.origin;
+  return stripTrailingSlash(origin);
+}
+function isLoopback(host) {
+  if (host.startsWith("[") && host.endsWith("]")) {
+    host = host.slice(1, -1);
+  }
+  return LOOPBACK_HOSTS.has(host);
+}
+function hostnameError(reason, input) {
+  return new TiroError(
+    {
+      code: "invalid_hostname",
+      message: `Refusing to use hostname "${input}": ${reason}.`,
+      errorType: "bad_request",
+      suggestion: "Use https://<host> (or http://localhost for local dev). If TIRO_HOSTNAME is set in your environment, unset it."
+    },
+    ExitCode.Usage
+  );
+}
 function getHostname(override) {
-  if (override) return stripTrailingSlash(override);
+  if (override !== void 0) return validateHostname(override);
   const env = process.env["TIRO_HOSTNAME"];
-  if (env) return stripTrailingSlash(env);
-  return stripTrailingSlash(config.get("hostname"));
+  if (env) return validateHostname(env);
+  return validateHostname(config.get("hostname"));
 }
-function getOauthClientId() {
+function getOauthClientId(hostname) {
   const id = config.get("oauthClientId");
   const registeredAt = config.get("oauthClientIdRegisteredAt");
+  const cachedHostname = config.get("oauthClientHostname");
   if (!id || !registeredAt) return null;
+  if (cachedHostname !== hostname) return null;
   const ttlMs = 29 * 24 * 60 * 60 * 1e3;
   if (Date.now() - registeredAt > ttlMs) return null;
   return id;
 }
-function setOauthClientId(clientId) {
+function setOauthClientId(clientId, hostname) {
   config.set("oauthClientId", clientId);
   config.set("oauthClientIdRegisteredAt", Date.now());
+  config.set("oauthClientHostname", hostname);
 }
 function clearOauthClientId() {
   config.set("oauthClientId", null);
   config.set("oauthClientIdRegisteredAt", null);
+  config.set("oauthClientHostname", null);
 }
 function stripTrailingSlash(s) {
   return s.endsWith("/") ? s.slice(0, -1) : s;
@@ -509,7 +582,7 @@ ${authorizeUrl}`);
       await openBrowser(authorizeUrl);
     }
     const callback = await loopback.waitForCallback(CALLBACK_TIMEOUT_MS);
-    if (callback.state !== state) {
+    if (!verifyState(callback.state, state)) {
       throw new TiroError(
         {
           code: "auth_state_mismatch",
@@ -544,7 +617,7 @@ ${authorizeUrl}`);
   }
 }
 async function ensureOauthClient(hostname, redirectUri) {
-  const cached = getOauthClientId();
+  const cached = getOauthClientId(hostname);
   if (cached) return cached;
   const url = `${hostname}/v1/mcp/oauth/register`;
   let res;
@@ -597,7 +670,7 @@ async function ensureOauthClient(hostname, redirectUri) {
       ExitCode.Generic
     );
   }
-  setOauthClientId(parsed.data.client_id);
+  setOauthClientId(parsed.data.client_id, hostname);
   return parsed.data.client_id;
 }
 function buildAuthorizeUrl(input) {
@@ -936,16 +1009,7 @@ var TiroApiClient = class {
     if (!res.ok) throw await mapHttpError(res, "DELETE", path);
   }
   buildUrl(path, params) {
-    const base = path.startsWith("http") ? path : `${this.hostname}${path}`;
-    const u = new URL(base);
-    if (params) {
-      for (const [k, v] of Object.entries(params)) {
-        if (v !== void 0 && v !== null && v !== "") {
-          u.searchParams.set(k, String(v));
-        }
-      }
-    }
-    return u.toString();
+    return buildApiUrl(this.hostname, path, params);
   }
   async fetch(url, init) {
     const headers = new Headers(init.headers);
@@ -1045,6 +1109,27 @@ async function tryParseApiError(res) {
     return null;
   }
 }
+function buildApiUrl(hostname, path, params) {
+  if (!path.startsWith("/") || path.startsWith("//") || path.startsWith("/\\")) {
+    throw new TiroError(
+      {
+        code: "internal_error",
+        message: `API path must start with a single "/": got ${JSON.stringify(path)}`,
+        errorType: "internal_error"
+      },
+      ExitCode.Generic
+    );
+  }
+  const u = new URL(`${hostname}${path}`);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0 && v !== null && v !== "") {
+        u.searchParams.set(k, String(v));
+      }
+    }
+  }
+  return u.toString();
+}
 function createApiClient(opts = {}) {
   if (opts.tokenOverride) {
     return new TiroApiClient(getHostname(opts.hostnameOverride), opts.tokenOverride);
@@ -1206,7 +1291,13 @@ function formatDuration(sec) {
 
 // src/commands/notes/search.ts
 import "commander";
-var SearchResponseSchema = PageCursorResponseSchema(NoteSchema).passthrough();
+import { z as z4 } from "zod";
+var SearchResponseSchema = z4.object({
+  notes: z4.array(NoteSchema),
+  nextCursor: z4.string().nullable(),
+  degraded: z4.boolean().optional(),
+  degradedReason: z4.string().nullable().optional()
+}).passthrough();
 var DEFAULT_PAGE_SIZE2 = 100;
 var MAX_PAGE_SIZE2 = 1e3;
 var HELP_AFTER2 = `
@@ -1276,13 +1367,22 @@ function registerNotesSearch(parent) {
       SearchResponseSchema,
       body
     );
-    const visible = opts.includeUntitled === true ? res.content : res.content.filter(isVisibleNote);
+    const visible = opts.includeUntitled === true ? res.notes : res.notes.filter(isVisibleNote);
     const mode = resolveOutputMode(globalOpts);
     if (mode === "json") {
       for (const note of visible) printNdjson(note);
       if (res.nextCursor) printNdjson({ _cursor: res.nextCursor });
+      if (res.degraded === true) {
+        printNdjson({ _degraded: true, _degradedReason: res.degradedReason ?? null });
+      }
     } else {
       printPretty2(visible, res.nextCursor, globalOpts);
+      if (res.degraded === true && globalOpts.quiet !== true) {
+        process.stderr.write(
+          `${color("\u26A0", "yellow", globalOpts)} search results are partial${res.degradedReason ? ` (${res.degradedReason})` : ""}
+`
+        );
+      }
     }
   });
 }
@@ -1319,8 +1419,33 @@ import "commander";
 
 // src/lib/output/file.ts
 import { mkdir, rename, stat, writeFile, access } from "fs/promises";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { dirname as dirname2, resolve as resolve2, sep } from "path";
+function assertSafeOutputPath(input) {
+  if (input.trim() === "") {
+    throw outputError("output path is empty", input);
+  }
+  const segments = input.split(/[\\/]/);
+  for (const seg of segments) {
+    if (seg === "..") {
+      throw outputError("path traversal segment '..' is not allowed", input);
+    }
+  }
+}
+function outputError(reason, input) {
+  return new TiroError(
+    {
+      code: "unsafe_output_path",
+      message: `Refusing to write to ${JSON.stringify(input)}: ${reason}.`,
+      errorType: "bad_request",
+      suggestion: "Use a path without '..' segments, or pass --force if you really mean it."
+    },
+    ExitCode.Usage
+  );
+}
 async function writeFileAtomic(filepath, content, opts = {}) {
+  if (!opts.force) {
+    assertSafeOutputPath(filepath);
+  }
   const absPath = resolve2(filepath);
   await mkdir(dirname2(absPath), { recursive: true });
   if (!opts.force) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theplato/tiro-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Tiro AI notes & transcripts — agent-first command line",
   "type": "module",
   "bin": {
@@ -22,7 +22,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run typecheck && npm run build"
+    "test:security": "vitest run --testNamePattern \"\\\\((C|H|M)[0-9]+\\\\)\"",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "keywords": [
     "tiro",