@theplato/tiro-cli 0.3.1 → 0.4.1

package/AGENTS.md

@@ -88,3 +88,16 @@ 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 posture (summary)
+
+- OAuth uses Authorization Code + PKCE with a CSRF-checked loopback
+  redirect. Tokens are held in the OS keychain or `TIRO_TOKEN` only —
+  never written to stdout, stderr, or disk in any other form.
+- `TIRO_HOSTNAME` / `--hostname` are validated against an `https://` (or
+  loopback) allowlist before any OAuth or API request runs.
+- `--output` paths that escape the working tree require `--force`.
+- A dedicated regression suite (`npm run test:security`) pins these
+  surfaces and runs in `prepublishOnly` — a broken defense blocks publish.
+
+Always run on the latest released version; older versions are deprecated.

package/README.md

@@ -108,7 +108,7 @@ tiro notes list
 ```bash
 tiro notes list                                              # pretty table in TTY
 tiro notes list --json                                       # NDJSON for pipes
-tiro notes list --keyword "OKR" --since 30d                  # OpenSearch reorder by keyword
+tiro notes list --keyword "OKR" --since 30d                  # Reorder by keyword relevance
 tiro notes list --folder <id> --limit 100 --cursor <token>
 ```
 
@@ -287,7 +287,7 @@ The CLI sits on the public Tiro API alongside the MCP server, sharing the same O
 
 ```
                     ┌──────────────────────────────┐
-                    │ Tiro Backend (Kotlin)         │
+                    │ Tiro Backend                  │
                     │  /v1/external/* + /v1/mcp/*   │
                     └──────────────┬────────────────┘
                                    │

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);
@@ -1113,17 +1198,18 @@ Examples:
   tiro notes list --folder <id> --limit 50
 
 Keyword matching:
-  --keyword reorders results by OpenSearch relevance (case-insensitive,
-  full-text against note title and paragraph content). When --keyword is
-  set, nextCursor is always null. Without --keyword, results are ordered
-  by createdAt desc.
+  --keyword reorders results by full-text relevance over title and
+  paragraph content (case-insensitive), with createdAt desc as tiebreaker
+  when scores are close. When --keyword is set, nextCursor is always null.
+  Without --keyword, results are ordered by recording time desc (falls back
+  to createdAt for memo-only notes).
 
 Note: placeholder notes (title='Untitled' or sourceType='onboarding') are
 filtered out by default. A page of N may return fewer than N visible notes \u2014
 keep paginating to fetch more, or pass --include-untitled to surface them.
 `;
 function registerNotesList(parent) {
-  parent.command("list").description("List notes (lightweight metadata).").option("--keyword <text>", 'Reorder by OpenSearch relevance for this keyword (e.g. "OKR")').option("--folder <id>", "Restrict to a folder and its descendants").option(
+  parent.command("list").description("List notes (lightweight metadata).").option("--keyword <text>", 'Reorder by full-text relevance for this keyword (e.g. "OKR")').option("--folder <id>", "Restrict to a folder and its descendants").option(
     "--since <date>",
     "Inclusive lower bound on createdAt (ISO-8601 or relative: 7d, 24h, 30m)"
   ).option("--until <date>", "Exclusive upper bound on createdAt").option(
@@ -1222,12 +1308,16 @@ Examples:
   tiro notes search "release" --since 2026-04-01 --until 2026-05-01
 
 Keyword matching:
-  Full-text against note title + paragraph content via OpenSearch.
-  Case-insensitive. Multi-word keywords are tokenized \u2014 "OKR planning"
-  matches notes containing both terms. The deep search variant (this
-  command) hydrates each result with its primary documents (one-pager,
-  custom) so an MCP/LLM client can read content alongside metadata in
-  one call.
+  Full-text search against note title + paragraph content. Case-insensitive.
+  Multi-word keywords are tokenized \u2014 "OKR planning" matches notes containing
+  both terms. The deep search variant (this command) hydrates each result
+  with its primary documents (one-pager, custom) so an MCP/LLM client can
+  read content alongside metadata in one call.
+
+Ordering:
+  Results are sorted by full-text relevance, then createdAt desc as
+  tiebreaker. Without --limit, the server returns 50 results (capped
+  at 200). Pass --limit to override.
 
 Note: placeholder notes (title='Untitled' or sourceType='onboarding') are
 filtered out by default. Pass --include-untitled to surface them.
@@ -1334,8 +1424,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.1",
+  "version": "0.4.1",
   "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",