@ekanos/cli 0.15.0 → 0.17.0

package/dist/safe-fs.d.ts

@@ -55,3 +55,21 @@ export declare function readBytesNoFollow(root: string, filePath: string): Buffe
 export declare function writeFileNoFollow(root: string, filePath: string, contents: string | Uint8Array): void;
 /** Append to an existing file under the same no-follow guarantee. */
 export declare function appendFileNoFollow(root: string, filePath: string, contents: string): void;
+/** Why `readPrivateFileNoFollow` would not read a file. */
+export type PrivateFileProblem = 'missing' | 'symlink' | 'not-a-file' | 'readable-by-others' | 'not-yours' | 'too-large';
+/**
+ * Read a file that holds a secret — a path a person or an agent named, not
+ * one inside a tree we write — only if it is a regular file, not a symlink
+ * (`O_NOFOLLOW` at open, and an `lstat` first for platforms without it),
+ * owned by this user and readable by no one else. Every check after the
+ * open runs on the open descriptor, so the file judged is the file read.
+ * Returns the bytes, or the reason it was refused.
+ */
+export declare function readPrivateFileNoFollow(filePath: string, maxBytes: number): {
+    ok: true;
+    bytes: Buffer;
+} | {
+    ok: false;
+    problem: PrivateFileProblem;
+    mode?: number;
+};

package/dist/safe-fs.js

@@ -205,6 +205,63 @@ export function appendFileNoFollow(root, filePath, contents) {
         fs.closeSync(fd);
     }
 }
+/**
+ * Read a file that holds a secret — a path a person or an agent named, not
+ * one inside a tree we write — only if it is a regular file, not a symlink
+ * (`O_NOFOLLOW` at open, and an `lstat` first for platforms without it),
+ * owned by this user and readable by no one else. Every check after the
+ * open runs on the open descriptor, so the file judged is the file read.
+ * Returns the bytes, or the reason it was refused.
+ */
+export function readPrivateFileNoFollow(filePath, maxBytes) {
+    try {
+        if (fs.lstatSync(filePath).isSymbolicLink()) {
+            return { ok: false, problem: 'symlink' };
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { ok: false, problem: 'missing' };
+        }
+        throw error;
+    }
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return { ok: false, problem: 'missing' };
+        if (code === 'ELOOP')
+            return { ok: false, problem: 'symlink' };
+        if (code === 'EISDIR')
+            return { ok: false, problem: 'not-a-file' };
+        throw error;
+    }
+    try {
+        const stats = fs.fstatSync(fd);
+        if (!stats.isFile())
+            return { ok: false, problem: 'not-a-file' };
+        // Mode bits and owners mean nothing on Windows; there the ACL governs.
+        if (process.platform !== 'win32') {
+            const mode = stats.mode & 0o777;
+            if ((mode & 0o077) !== 0) {
+                return { ok: false, problem: 'readable-by-others', mode };
+            }
+            if (typeof process.getuid === 'function' &&
+                stats.uid !== process.getuid()) {
+                return { ok: false, problem: 'not-yours' };
+            }
+        }
+        if (stats.size > maxBytes)
+            return { ok: false, problem: 'too-large' };
+        return { ok: true, bytes: fs.readFileSync(fd) };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /**
  * `O_NOFOLLOW` is POSIX and present on Linux and macOS. Node exposes it as 0
  * where the platform has no equivalent (Windows), in which case the explicit

package/dist/safe-fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe-fs.js","sourceRoot":"","sources":["../src/safe-fs.ts"],"names":[],"mappings":";AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,MAAc;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY,EAAE,MAAc;IACpD,MAAM,iBAAiB,CACrB,qBAAqB,MAAM,yBAAyB,IAAI,GAAG,EAC3D,sEAAsE;QACpE,cAAc,CACjB,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,iBAAiB,CACrB,yCAAyC,IAAI,GAAG,EAChD,yEAAyE,IAAI,GAAG;QAC9E,yCAAyC,CAC5C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAY,EAAE,MAAc;IACrE,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC;QAAE,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAE/D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO;IAE5B,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YACH,KAAK,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;mBAAO,CAAC;YACP,qEAAqE;YACrE,kBAAkB;YAClB,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,cAAc,EAAE;YAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IACpD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,GAAW;IACjD,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC;QAAE,gBAAgB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAEzD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO;IAE5B,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,KAAK,GAAoB,IAAI,CAAC;QAClC,IAAI,CAAC;YACH,KAAK,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;mBAAO,CAAC;YACP,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;QAED,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,IAAI,CAAC;gBACH,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;gBACnD,8DAA8D;gBAC9D,IAAI,IAAI,KAAK,QAAQ;oBAAE,MAAM,KAAK,CAAC;gBACnC,KAAK,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAChC,CAAC;YACD,IAAI,KAAK,KAAK,IAAI;gBAAE,SAAS;QAC/B,CAAC;QAED,IAAI,KAAK,CAAC,cAAc,EAAE;YAAE,YAAY,CAAC,OAAO,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,MAAM,iBAAiB,CACrB,GAAG,OAAO,oDAAoD;gBAC5D,gBAAgB,EAClB,kBAAkB,OAAO,4BAA4B,CACtD,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AASD,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACzE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,EAAE;QAAE,OAAO,SAAS,CAAC;IAC7C,IAAI,KAAK,CAAC,WAAW,EAAE;QAAE,OAAO,WAAW,CAAC;IAC5C,IAAI,KAAK,CAAC,MAAM,EAAE;QAAE,OAAO,MAAM,CAAC;IAClC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,QAAgB;;;IAEhB,aAAO,MAAA,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,0CAAE,QAAQ,CAAC,MAAM,CAAC,mCAAI,IAAI,CAAC;AACrE,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,QAAgB;IAEhB,0BAA0B,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAE3C,IAAI,EAAU,CAAC;IACf,IAAI,CAAC;QACH,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,GAAG,UAAU,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;QACnD,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACnC,IAAI,IAAI,KAAK,OAAO;YAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,QAAgB,EAChB,QAA6B;IAE7B,0BAA0B,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3C,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAExC,IAAI,EAAU,CAAC;IACf,IAAI,CAAC;QACH,EAAE,GAAG,EAAE,CAAC,QAAQ,CACd,QAAQ,EACR,EAAE,CAAC,SAAS,CAAC,QAAQ;YACnB,EAAE,CAAC,SAAS,CAAC,OAAO;YACpB,EAAE,CAAC,SAAS,CAAC,OAAO;YACpB,UAAU,EACZ,KAAK,CACN,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;QACnD,IAAI,IAAI,KAAK,OAAO;YAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,QAAgB,EAChB,QAAgB;IAEhB,0BAA0B,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAE3C,IAAI,EAAU,CAAC;IACf,IAAI,CAAC;QACH,EAAE,GAAG,EAAE,CAAC,QAAQ,CACd,QAAQ,EACR,EAAE,CAAC,SAAS,CAAC,QAAQ,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,GAAG,UAAU,CAC3D,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;QACnD,IAAI,IAAI,KAAK,OAAO;YAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAG,EAAE,CAAC,SAAS,CAAC,UAAU,mCAAI,CAAC,CAAC","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { invalidStateError } from './errors';\n\n/**\n * Filesystem primitives for writing into a directory we do not fully trust.\n *\n * `ekanos dev` writes a generated tree into a partner's project, and every\n * path it touches is one an attacker (or a careless `ln -s`) may have created\n * first. Plain `existsSync` + `writeFileSync` follows symlinks, so a\n * `.ekanos/harness` pointing at `~/.ssh`, a generated leaf pointing at a\n * tracked source file, or a DANGLING link (which `existsSync` reports as\n * absent, and which `writeFileSync` then materializes) all let a scaffold\n * write outside the project.\n *\n * Two invariants close that, and both are enforced here rather than at the\n * call sites, because a single unguarded write anywhere reopens the hole:\n *\n *  1. **Containment** — every path resolves inside the project root.\n *  2. **No symlinks** — no component of a path we write through may be a\n *     symlink, and the write itself uses `O_NOFOLLOW` so the kernel enforces\n *     it at open time rather than trusting our earlier `lstat`. That closes\n *     the check→write TOCTOU window: a link swapped in after the check makes\n *     `open` fail with ELOOP instead of following.\n */\n\n/** True when `target` is inside `root` (or is `root` itself). */\nexport function isContained(root: string, target: string): boolean {\n  const relative = path.relative(root, target);\n  if (relative === '') return true;\n  return !relative.startsWith('..') && !path.isAbsolute(relative);\n}\n\nfunction containmentError(root: string, target: string): never {\n  throw invalidStateError(\n    `Refusing to write ${target}: it resolves outside ${root}.`,\n    'Remove the symlink or path component that redirects it, then re-run ' +\n      'the command.',\n  );\n}\n\nfunction symlinkError(link: string): never {\n  throw invalidStateError(\n    `Refusing to write through the symlink ${link}.`,\n    `The CLI only writes real files inside the folder it writes to. Delete ${link} ` +\n      '(or the tree containing it) and re-run.',\n  );\n}\n\n/**\n * Walk every path component from `root` down to `target` and refuse if any\n * existing one is a symlink. `lstat` is deliberate — `stat` would resolve the\n * link and report the target's type, which is exactly what we must not do.\n */\nexport function assertNoSymlinkedComponent(root: string, target: string): void {\n  if (!isContained(root, target)) containmentError(root, target);\n\n  const relative = path.relative(root, target);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      // Does not exist yet — nothing to follow, and everything below it is\n      // ours to create.\n      return;\n    }\n    if (stats.isSymbolicLink()) symlinkError(current);\n  }\n}\n\n/**\n * `mkdir -p`, one guarded component at a time. `fs.mkdirSync(recursive)` is\n * happy to walk through a symlinked ancestor; this is not.\n */\nexport function mkdirSafe(root: string, dir: string): void {\n  if (!isContained(root, dir)) containmentError(root, dir);\n\n  const relative = path.relative(root, dir);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats | null = null;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      stats = null;\n    }\n\n    if (stats === null) {\n      try {\n        fs.mkdirSync(current);\n      } catch (error) {\n        const code = (error as NodeJS.ErrnoException).code;\n        // Lost a race to another process; re-check what landed there.\n        if (code !== 'EEXIST') throw error;\n        stats = fs.lstatSync(current);\n      }\n      if (stats === null) continue;\n    }\n\n    if (stats.isSymbolicLink()) symlinkError(current);\n    if (!stats.isDirectory()) {\n      throw invalidStateError(\n        `${current} exists and is not a directory, so nothing can be ` +\n          'written there.',\n        `Move or delete ${current}, then re-run the command.`,\n      );\n    }\n  }\n}\n\n/**\n * What `destPath` currently is, without following anything. `'symlink'` is\n * reported for a dangling link too — the case `existsSync` calls absent and\n * `writeFileSync` would silently materialize outside the project.\n */\nexport type PathKind = 'missing' | 'file' | 'directory' | 'symlink' | 'other';\n\nexport function classifyPath(destPath: string): PathKind {\n  let stats: fs.Stats;\n  try {\n    stats = fs.lstatSync(destPath);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';\n    throw error;\n  }\n  if (stats.isSymbolicLink()) return 'symlink';\n  if (stats.isDirectory()) return 'directory';\n  if (stats.isFile()) return 'file';\n  return 'other';\n}\n\n/**\n * Read a file, refusing to follow a symlink at the final component. Returns\n * null when it does not exist. `O_NOFOLLOW` makes the kernel enforce this, so\n * there is no window between deciding and reading.\n */\nexport function readFileNoFollow(\n  root: string,\n  filePath: string,\n): string | null {\n  return readBytesNoFollow(root, filePath)?.toString('utf8') ?? null;\n}\n\n/** `readFileNoFollow`, as bytes — for comparing a binary file exactly. */\nexport function readBytesNoFollow(\n  root: string,\n  filePath: string,\n): Buffer | null {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return null;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    return fs.readFileSync(fd);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * Write a file, creating parent directories, refusing every symlink on the\n * way and at the leaf. `O_NOFOLLOW` on the final open is what makes this safe\n * against a link swapped in after our checks.\n */\nexport function writeFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string | Uint8Array,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n  mkdirSafe(root, path.dirname(filePath));\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY |\n        fs.constants.O_CREAT |\n        fs.constants.O_TRUNC |\n        O_NOFOLLOW,\n      0o644,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/** Append to an existing file under the same no-follow guarantee. */\nexport function appendFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY | fs.constants.O_APPEND | O_NOFOLLOW,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * `O_NOFOLLOW` is POSIX and present on Linux and macOS. Node exposes it as 0\n * where the platform has no equivalent (Windows), in which case the explicit\n * `lstat` walk above is the whole guarantee rather than a belt to the kernel's\n * braces.\n */\nconst O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;\n"]}
+{"version":3,"file":"safe-fs.js","sourceRoot":"","sources":["../src/safe-fs.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { invalidStateError } from './errors';\n\n/**\n * Filesystem primitives for writing into a directory we do not fully trust.\n *\n * `ekanos dev` writes a generated tree into a partner's project, and every\n * path it touches is one an attacker (or a careless `ln -s`) may have created\n * first. Plain `existsSync` + `writeFileSync` follows symlinks, so a\n * `.ekanos/harness` pointing at `~/.ssh`, a generated leaf pointing at a\n * tracked source file, or a DANGLING link (which `existsSync` reports as\n * absent, and which `writeFileSync` then materializes) all let a scaffold\n * write outside the project.\n *\n * Two invariants close that, and both are enforced here rather than at the\n * call sites, because a single unguarded write anywhere reopens the hole:\n *\n *  1. **Containment** — every path resolves inside the project root.\n *  2. **No symlinks** — no component of a path we write through may be a\n *     symlink, and the write itself uses `O_NOFOLLOW` so the kernel enforces\n *     it at open time rather than trusting our earlier `lstat`. That closes\n *     the check→write TOCTOU window: a link swapped in after the check makes\n *     `open` fail with ELOOP instead of following.\n */\n\n/** True when `target` is inside `root` (or is `root` itself). */\nexport function isContained(root: string, target: string): boolean {\n  const relative = path.relative(root, target);\n  if (relative === '') return true;\n  return !relative.startsWith('..') && !path.isAbsolute(relative);\n}\n\nfunction containmentError(root: string, target: string): never {\n  throw invalidStateError(\n    `Refusing to write ${target}: it resolves outside ${root}.`,\n    'Remove the symlink or path component that redirects it, then re-run ' +\n      'the command.',\n  );\n}\n\nfunction symlinkError(link: string): never {\n  throw invalidStateError(\n    `Refusing to write through the symlink ${link}.`,\n    `The CLI only writes real files inside the folder it writes to. Delete ${link} ` +\n      '(or the tree containing it) and re-run.',\n  );\n}\n\n/**\n * Walk every path component from `root` down to `target` and refuse if any\n * existing one is a symlink. `lstat` is deliberate — `stat` would resolve the\n * link and report the target's type, which is exactly what we must not do.\n */\nexport function assertNoSymlinkedComponent(root: string, target: string): void {\n  if (!isContained(root, target)) containmentError(root, target);\n\n  const relative = path.relative(root, target);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      // Does not exist yet — nothing to follow, and everything below it is\n      // ours to create.\n      return;\n    }\n    if (stats.isSymbolicLink()) symlinkError(current);\n  }\n}\n\n/**\n * `mkdir -p`, one guarded component at a time. `fs.mkdirSync(recursive)` is\n * happy to walk through a symlinked ancestor; this is not.\n */\nexport function mkdirSafe(root: string, dir: string): void {\n  if (!isContained(root, dir)) containmentError(root, dir);\n\n  const relative = path.relative(root, dir);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats | null = null;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      stats = null;\n    }\n\n    if (stats === null) {\n      try {\n        fs.mkdirSync(current);\n      } catch (error) {\n        const code = (error as NodeJS.ErrnoException).code;\n        // Lost a race to another process; re-check what landed there.\n        if (code !== 'EEXIST') throw error;\n        stats = fs.lstatSync(current);\n      }\n      if (stats === null) continue;\n    }\n\n    if (stats.isSymbolicLink()) symlinkError(current);\n    if (!stats.isDirectory()) {\n      throw invalidStateError(\n        `${current} exists and is not a directory, so nothing can be ` +\n          'written there.',\n        `Move or delete ${current}, then re-run the command.`,\n      );\n    }\n  }\n}\n\n/**\n * What `destPath` currently is, without following anything. `'symlink'` is\n * reported for a dangling link too — the case `existsSync` calls absent and\n * `writeFileSync` would silently materialize outside the project.\n */\nexport type PathKind = 'missing' | 'file' | 'directory' | 'symlink' | 'other';\n\nexport function classifyPath(destPath: string): PathKind {\n  let stats: fs.Stats;\n  try {\n    stats = fs.lstatSync(destPath);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';\n    throw error;\n  }\n  if (stats.isSymbolicLink()) return 'symlink';\n  if (stats.isDirectory()) return 'directory';\n  if (stats.isFile()) return 'file';\n  return 'other';\n}\n\n/**\n * Read a file, refusing to follow a symlink at the final component. Returns\n * null when it does not exist. `O_NOFOLLOW` makes the kernel enforce this, so\n * there is no window between deciding and reading.\n */\nexport function readFileNoFollow(\n  root: string,\n  filePath: string,\n): string | null {\n  return readBytesNoFollow(root, filePath)?.toString('utf8') ?? null;\n}\n\n/** `readFileNoFollow`, as bytes — for comparing a binary file exactly. */\nexport function readBytesNoFollow(\n  root: string,\n  filePath: string,\n): Buffer | null {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return null;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    return fs.readFileSync(fd);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * Write a file, creating parent directories, refusing every symlink on the\n * way and at the leaf. `O_NOFOLLOW` on the final open is what makes this safe\n * against a link swapped in after our checks.\n */\nexport function writeFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string | Uint8Array,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n  mkdirSafe(root, path.dirname(filePath));\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY |\n        fs.constants.O_CREAT |\n        fs.constants.O_TRUNC |\n        O_NOFOLLOW,\n      0o644,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/** Append to an existing file under the same no-follow guarantee. */\nexport function appendFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY | fs.constants.O_APPEND | O_NOFOLLOW,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/** Why `readPrivateFileNoFollow` would not read a file. */\nexport type PrivateFileProblem =\n  | 'missing'\n  | 'symlink'\n  | 'not-a-file'\n  | 'readable-by-others'\n  | 'not-yours'\n  | 'too-large';\n\n/**\n * Read a file that holds a secret — a path a person or an agent named, not\n * one inside a tree we write — only if it is a regular file, not a symlink\n * (`O_NOFOLLOW` at open, and an `lstat` first for platforms without it),\n * owned by this user and readable by no one else. Every check after the\n * open runs on the open descriptor, so the file judged is the file read.\n * Returns the bytes, or the reason it was refused.\n */\nexport function readPrivateFileNoFollow(\n  filePath: string,\n  maxBytes: number,\n):\n  | { ok: true; bytes: Buffer }\n  | { ok: false; problem: PrivateFileProblem; mode?: number } {\n  try {\n    if (fs.lstatSync(filePath).isSymbolicLink()) {\n      return { ok: false, problem: 'symlink' };\n    }\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n      return { ok: false, problem: 'missing' };\n    }\n    throw error;\n  }\n\n  let fd: number;\n  try {\n    fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return { ok: false, problem: 'missing' };\n    if (code === 'ELOOP') return { ok: false, problem: 'symlink' };\n    if (code === 'EISDIR') return { ok: false, problem: 'not-a-file' };\n    throw error;\n  }\n\n  try {\n    const stats = fs.fstatSync(fd);\n    if (!stats.isFile()) return { ok: false, problem: 'not-a-file' };\n    // Mode bits and owners mean nothing on Windows; there the ACL governs.\n    if (process.platform !== 'win32') {\n      const mode = stats.mode & 0o777;\n      if ((mode & 0o077) !== 0) {\n        return { ok: false, problem: 'readable-by-others', mode };\n      }\n      if (\n        typeof process.getuid === 'function' &&\n        stats.uid !== process.getuid()\n      ) {\n        return { ok: false, problem: 'not-yours' };\n      }\n    }\n    if (stats.size > maxBytes) return { ok: false, problem: 'too-large' };\n    return { ok: true, bytes: fs.readFileSync(fd) };\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * `O_NOFOLLOW` is POSIX and present on Linux and macOS. Node exposes it as 0\n * where the platform has no equivalent (Windows), in which case the explicit\n * `lstat` walk above is the whole guarantee rather than a belt to the kernel's\n * braces.\n */\nconst O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;\n"]}

package/dist/secret-form.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The "little GUI" for a secret: a one-shot form served by the CLI itself on
+ * this computer, for a run with no terminal to type into (a coding agent, a
+ * script) but a person at the desktop. The person types the secret into
+ * their own browser; it goes from there to this process and on to the host,
+ * and never to stdout, stderr, a log or the `--json` envelope — so an agent
+ * driving the CLI starts the form and never sees what was entered.
+ *
+ * What keeps it to that one person and that one submission:
+ *
+ *  - **Loopback only.** It listens on 127.0.0.1, on a port the OS picks.
+ *  - **An unguessable path.** 256 random bits; any other path is a 404.
+ *  - **Host and Origin.** A request whose `Host` is not exactly
+ *    `127.0.0.1:<port>` is refused (a DNS-rebinding page names its own
+ *    host), and a submission must carry this form's `Origin` — so another
+ *    page in the same browser cannot post to it.
+ *  - **One use, short life.** The first good submission closes the server;
+ *    so does the timeout, which fails the command rather than waiting on.
+ *  - **A page that loads nothing.** No script, no external asset: a CSP of
+ *    `default-src 'none'` with one nonce'd stylesheet, never framed, never
+ *    cached, no referrer.
+ */
+export interface SecretFormField {
+    name: string;
+    label: string;
+    sensitive: boolean;
+    description?: string;
+    required?: boolean;
+    /** A value is saved already: leaving it empty keeps it. */
+    set?: boolean;
+    /** A non-secret field's saved value, shown as the placeholder. Never a secret. */
+    value?: string | null;
+}
+export interface SecretFormOptions {
+    title: string;
+    fields: readonly SecretFormField[];
+    /** Opens the form's URL in the person's browser. */
+    open: (url: string) => void;
+    /** How long to wait for the submission (default five minutes). */
+    timeoutMs?: number;
+}
+export declare const SECRET_FORM_TIMEOUT_MS: number;
+/**
+ * Serve the form, open it, and resolve with what was submitted: each field's
+ * value by name, empty ones left out. Rejects on the timeout.
+ */
+export declare function collectWithSecretForm(options: SecretFormOptions): Promise<Record<string, string>>;
+export declare function escapeHtml(value: string): string;

package/dist/secret-form.js

@@ -0,0 +1,212 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import * as http from 'node:http';
+import { validationError } from './errors.js';
+export const SECRET_FORM_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_BODY_BYTES = 64 * 1024;
+/**
+ * Serve the form, open it, and resolve with what was submitted: each field's
+ * value by name, empty ones left out. Rejects on the timeout.
+ */
+export function collectWithSecretForm(options) {
+    var _a;
+    const token = randomBytes(32).toString('base64url');
+    const nonce = randomBytes(16).toString('base64');
+    const timeoutMs = (_a = options.timeoutMs) !== null && _a !== void 0 ? _a : SECRET_FORM_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let origin = '';
+        let hostHeader = '';
+        const server = http.createServer((request, response) => {
+            handle(request, response).catch(() => {
+                if (!response.headersSent)
+                    send(response, 500, page('Something went wrong', 'Return to your terminal.'));
+            });
+        });
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            server.closeAllConnections();
+            outcome();
+        };
+        const timer = setTimeout(() => {
+            finish(() => reject(validationError(`The secure form was not submitted within ${duration(timeoutMs)}; nothing was saved.`, 'Run the command again for a fresh form, or pass the secret with --secret-env, --secret-file or --secret-stdin.')));
+        }, timeoutMs);
+        const send = (response, status, body) => {
+            response.writeHead(status, {
+                'content-type': 'text/html; charset=utf-8',
+                'cache-control': 'no-store',
+                'content-security-policy': `default-src 'none'; style-src 'nonce-${nonce}'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'`,
+                'x-frame-options': 'DENY',
+                'x-content-type-options': 'nosniff',
+                'referrer-policy': 'no-referrer',
+                'cross-origin-resource-policy': 'same-origin',
+            });
+            response.end(body);
+        };
+        const page = (heading, text, inner = '') => [
+            '<!doctype html>',
+            '<html lang="en"><head><meta charset="utf-8">',
+            '<meta name="viewport" content="width=device-width, initial-scale=1">',
+            '<meta name="referrer" content="no-referrer">',
+            `<title>${escapeHtml(heading)} · ekanos</title>`,
+            `<style nonce="${nonce}">${STYLE}</style>`,
+            '</head><body><main>',
+            `<h1>${escapeHtml(heading)}</h1>`,
+            `<p class="lede">${escapeHtml(text)}</p>`,
+            inner,
+            '</main></body></html>',
+        ].join('');
+        const isOurPath = (pathname) => {
+            const expected = Buffer.from(`/${token}`);
+            const given = Buffer.from(pathname);
+            return (given.length === expected.length && timingSafeEqual(given, expected));
+        };
+        async function handle(request, response) {
+            var _a, _b, _c;
+            if (settled) {
+                send(response, 410, page('This form is closed', 'Return to your terminal.'));
+                return;
+            }
+            if (request.headers.host !== hostHeader) {
+                send(response, 421, page('Wrong address', 'Open the link the ekanos CLI opened.'));
+                return;
+            }
+            const pathname = (_b = ((_a = request.url) !== null && _a !== void 0 ? _a : '').split('?')[0]) !== null && _b !== void 0 ? _b : '';
+            if (!isOurPath(pathname)) {
+                send(response, 404, page('Not found', 'Open the link the ekanos CLI opened.'));
+                return;
+            }
+            if (request.method === 'GET') {
+                send(response, 200, formPage());
+                return;
+            }
+            if (request.method !== 'POST') {
+                response.setHeader('allow', 'GET, POST');
+                send(response, 405, page('Not allowed', 'Return to your terminal.'));
+                return;
+            }
+            const fetchSite = request.headers['sec-fetch-site'];
+            if (request.headers.origin !== origin ||
+                (fetchSite !== undefined && fetchSite !== 'same-origin')) {
+                send(response, 403, page('Refused', 'This form only accepts what is typed into it.'));
+                return;
+            }
+            if (!((_c = request.headers['content-type']) !== null && _c !== void 0 ? _c : '')
+                .toLowerCase()
+                .startsWith('application/x-www-form-urlencoded')) {
+                send(response, 415, page('Refused', 'Submit the form itself.'));
+                return;
+            }
+            const body = await readBody(request);
+            if (body === null) {
+                send(response, 413, page('Too large', 'Return to your terminal.'));
+                return;
+            }
+            const params = new URLSearchParams(body);
+            const values = {};
+            options.fields.forEach((field, index) => {
+                var _a;
+                const value = ((_a = params.get(`f${index}`)) !== null && _a !== void 0 ? _a : '').trim();
+                if (value)
+                    values[field.name] = value;
+            });
+            send(response, 200, page('Received', 'The ekanos CLI has what you entered and is saving it. You can close this tab and return to your terminal.'));
+            finish(() => resolve(values));
+        }
+        function formPage() {
+            const inputs = options.fields
+                .map((field, index) => {
+                const id = `f${index}`;
+                const placeholder = field.sensitive
+                    ? field.set
+                        ? 'Saved — leave empty to keep it'
+                        : ''
+                    : field.set
+                        ? field.value
+                            ? `Current: ${field.value} — leave empty to keep it`
+                            : 'Saved — leave empty to keep it'
+                        : '';
+                const required = field.required && !field.set;
+                return [
+                    '<div class="field">',
+                    `<label for="${id}">${escapeHtml(field.label)}${required ? '' : ' <span class="optional">(optional)</span>'}</label>`,
+                    field.description
+                        ? `<p class="help" id="${id}-help">${escapeHtml(field.description)}</p>`
+                        : '',
+                    `<input id="${id}" name="${id}" type="${field.sensitive ? 'password' : 'text'}"`,
+                    ' autocomplete="off" autocapitalize="off" spellcheck="false"',
+                    placeholder ? ` placeholder="${escapeHtml(placeholder)}"` : '',
+                    field.description ? ` aria-describedby="${id}-help"` : '',
+                    required ? ' required' : '',
+                    index === 0 ? ' autofocus' : '',
+                    '>',
+                    '</div>',
+                ].join('');
+            })
+                .join('');
+            return page(options.title, 'This page is served by the ekanos CLI on your own computer. What you enter goes only to it, then to Ekanos over HTTPS — never to your terminal, a log or the agent that ran the command. It works once and closes.', `<form method="post" action="/${token}">${inputs}<button type="submit">Save</button></form>`);
+        }
+        server.on('error', (error) => finish(() => reject(error)));
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            origin = `http://127.0.0.1:${port}`;
+            hostHeader = `127.0.0.1:${port}`;
+            try {
+                options.open(`${origin}/${token}`);
+            }
+            catch (_a) {
+                // The timeout still ends the wait.
+            }
+        });
+    });
+}
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let tooLarge = false;
+        request.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                tooLarge = true;
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on('end', () => resolve(tooLarge ? null : Buffer.concat(chunks).toString('utf8')));
+        request.on('error', reject);
+    });
+}
+function duration(ms) {
+    if (ms < 60000) {
+        const seconds = Math.max(1, Math.ceil(ms / 1000));
+        return `${seconds} second${seconds === 1 ? '' : 's'}`;
+    }
+    const minutes = Math.round(ms / 60000);
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+}
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const STYLE = [
+    ':root{color-scheme:light dark;font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;line-height:1.5}',
+    'body{margin:0;display:flex;justify-content:center;padding:48px 16px}',
+    'main{width:100%;max-width:440px}',
+    'h1{font-size:1.25rem;margin:0 0 8px}',
+    '.lede{margin:0 0 24px;opacity:.75;font-size:.9rem}',
+    '.field{margin:0 0 16px}',
+    'label{display:block;font-weight:600;font-size:.9rem;margin:0 0 4px}',
+    '.optional{font-weight:400;opacity:.6}',
+    '.help{margin:0 0 6px;font-size:.85rem;opacity:.7}',
+    'input{box-sizing:border-box;width:100%;padding:8px 10px;font:inherit;border:1px solid #8888;border-radius:6px;background:transparent;color:inherit}',
+    'button{margin-top:8px;padding:8px 16px;font:inherit;font-weight:600;border:1px solid currentColor;border-radius:6px;background:transparent;color:inherit;cursor:pointer}',
+].join('');
+//# sourceMappingURL=secret-form.js.map

package/dist/secret-form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-form.js","sourceRoot":"","sources":["../src/secret-form.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAGlC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AA8C3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACpD,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAA0B;;IAE1B,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,SAAS,SAAG,OAAO,CAAC,SAAS,mCAAI,sBAAsB,CAAC;IAE9D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,UAAU,GAAG,EAAE,CAAC;QAEpB,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;YACrD,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBACnC,IAAI,CAAC,QAAQ,CAAC,WAAW;oBACvB,IAAI,CACF,QAAQ,EACR,GAAG,EACH,IAAI,CAAC,sBAAsB,EAAE,0BAA0B,CAAC,CACzD,CAAC;YACN,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,CAAC,OAAmB,EAAE,EAAE;YACrC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,mBAAmB,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QAEF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,CAAC,GAAG,EAAE,CACV,MAAM,CACJ,eAAe,CACb,4CAA4C,QAAQ,CAAC,SAAS,CAAC,sBAAsB,EACrF,gHAAgH,CACjH,CACF,CACF,CAAC;QACJ,CAAC,EAAE,SAAS,CAAC,CAAC;QAEd,MAAM,IAAI,GAAG,CACX,QAA6B,EAC7B,MAAc,EACd,IAAY,EACZ,EAAE;YACF,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE;gBACzB,cAAc,EAAE,0BAA0B;gBAC1C,eAAe,EAAE,UAAU;gBAC3B,yBAAyB,EAAE,wCAAwC,KAAK,gEAAgE;gBACxI,iBAAiB,EAAE,MAAM;gBACzB,wBAAwB,EAAE,SAAS;gBACnC,iBAAiB,EAAE,aAAa;gBAChC,8BAA8B,EAAE,aAAa;aAC9C,CAAC,CAAC;YACH,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC,CAAC;QAEF,MAAM,IAAI,GAAG,CAAC,OAAe,EAAE,IAAY,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CACzD;YACE,iBAAiB;YACjB,8CAA8C;YAC9C,sEAAsE;YACtE,8CAA8C;YAC9C,UAAU,UAAU,CAAC,OAAO,CAAC,mBAAmB;YAChD,iBAAiB,KAAK,KAAK,KAAK,UAAU;YAC1C,qBAAqB;YACrB,OAAO,UAAU,CAAC,OAAO,CAAC,OAAO;YACjC,mBAAmB,UAAU,CAAC,IAAI,CAAC,MAAM;YACzC,KAAK;YACL,uBAAuB;SACxB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEb,MAAM,SAAS,GAAG,CAAC,QAAgB,EAAW,EAAE;YAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC;YAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACpC,OAAO,CACL,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,CACrE,CAAC;QACJ,CAAC,CAAC;QAEF,KAAK,UAAU,MAAM,CACnB,OAA6B,EAC7B,QAA6B;;YAE7B,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CACF,QAAQ,EACR,GAAG,EACH,IAAI,CAAC,qBAAqB,EAAE,0BAA0B,CAAC,CACxD,CAAC;gBACF,OAAO;YACT,CAAC;YACD,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBACxC,IAAI,CACF,QAAQ,EACR,GAAG,EACH,IAAI,CAAC,eAAe,EAAE,sCAAsC,CAAC,CAC9D,CAAC;gBACF,OAAO;YACT,CAAC;YACD,MAAM,QAAQ,SAAG,OAAC,OAAO,CAAC,GAAG,mCAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,mCAAI,EAAE,CAAC;YACzD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACzB,IAAI,CACF,QAAQ,EACR,GAAG,EACH,IAAI,CAAC,WAAW,EAAE,sCAAsC,CAAC,CAC1D,CAAC;gBACF,OAAO;YACT,CAAC;YAED,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;gBAC7B,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;gBAChC,OAAO;YACT,CAAC;YACD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC9B,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;gBACzC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,0BAA0B,CAAC,CAAC,CAAC;gBACrE,OAAO;YACT,CAAC;YAED,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;YACpD,IACE,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM;gBACjC,CAAC,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,aAAa,CAAC,EACxD,CAAC;gBACD,IAAI,CACF,QAAQ,EACR,GAAG,EACH,IAAI,CAAC,SAAS,EAAE,+CAA+C,CAAC,CACjE,CAAC;gBACF,OAAO;YACT,CAAC;YACD,IACE,CAAC,OAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,mCAAI,EAAE,CAAC;iBACrC,WAAW,EAAE;iBACb,UAAU,CAAC,mCAAmC,CAAC,EAClD,CAAC;gBACD,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,yBAAyB,CAAC,CAAC,CAAC;gBAChE,OAAO;YACT,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;YACrC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,0BAA0B,CAAC,CAAC,CAAC;gBACnE,OAAO;YACT,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,MAAM,GAA2B,EAAE,CAAC;YAC1C,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;;gBACtC,MAAM,KAAK,GAAG,OAAC,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC,mCAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBACrD,IAAI,KAAK;oBAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YACxC,CAAC,CAAC,CAAC;YAEH,IAAI,CACF,QAAQ,EACR,GAAG,EACH,IAAI,CACF,UAAU,EACV,2GAA2G,CAC5G,CACF,CAAC;YACF,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAChC,CAAC;QAED,SAAS,QAAQ;YACf,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM;iBAC1B,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;gBACpB,MAAM,EAAE,GAAG,IAAI,KAAK,EAAE,CAAC;gBACvB,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS;oBACjC,CAAC,CAAC,KAAK,CAAC,GAAG;wBACT,CAAC,CAAC,gCAAgC;wBAClC,CAAC,CAAC,EAAE;oBACN,CAAC,CAAC,KAAK,CAAC,GAAG;wBACT,CAAC,CAAC,KAAK,CAAC,KAAK;4BACX,CAAC,CAAC,YAAY,KAAK,CAAC,KAAK,2BAA2B;4BACpD,CAAC,CAAC,gCAAgC;wBACpC,CAAC,CAAC,EAAE,CAAC;gBACT,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;gBAC9C,OAAO;oBACL,qBAAqB;oBACrB,eAAe,EAAE,KAAK,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,2CAA2C,UAAU;oBACrH,KAAK,CAAC,WAAW;wBACf,CAAC,CAAC,uBAAuB,EAAE,UAAU,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM;wBACxE,CAAC,CAAC,EAAE;oBACN,cAAc,EAAE,WAAW,EAAE,WAAW,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,GAAG;oBAChF,6DAA6D;oBAC7D,WAAW,CAAC,CAAC,CAAC,iBAAiB,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;oBAC9D,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE;oBACzD,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;oBAC3B,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;oBAC/B,GAAG;oBACH,QAAQ;iBACT,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACb,CAAC,CAAC;iBACD,IAAI,CAAC,EAAE,CAAC,CAAC;YACZ,OAAO,IAAI,CACT,OAAO,CAAC,KAAK,EACb,oNAAoN,EACpN,gCAAgC,KAAK,KAAK,MAAM,4CAA4C,CAC7F,CAAC;QACJ,CAAC;QAED,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;YACjC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,EAAiB,CAAC;YACjD,MAAM,GAAG,oBAAoB,IAAI,EAAE,CAAC;YACpC,UAAU,GAAG,aAAa,IAAI,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC,CAAC;YACrC,CAAC;uBAAO,CAAC;gBACP,mCAAmC;YACrC,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,OAA6B;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACnC,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;YACrB,IAAI,IAAI,GAAG,cAAc,EAAE,CAAC;gBAC1B,QAAQ,GAAG,IAAI,CAAC;gBAChB,OAAO;YACT,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CACrB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAClE,CAAC;QACF,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,EAAU;IAC1B,IAAI,EAAE,GAAG,KAAM,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QAClD,OAAO,GAAG,OAAO,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IACxD,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,KAAM,CAAC,CAAC;IACxC,OAAO,GAAG,OAAO,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK;SACT,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,KAAK,GAAG;IACZ,wHAAwH;IACxH,sEAAsE;IACtE,kCAAkC;IAClC,sCAAsC;IACtC,oDAAoD;IACpD,yBAAyB;IACzB,qEAAqE;IACrE,uCAAuC;IACvC,mDAAmD;IACnD,qJAAqJ;IACrJ,0KAA0K;CAC3K,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC","sourcesContent":["import { randomBytes, timingSafeEqual } from 'node:crypto';\nimport * as http from 'node:http';\nimport type { AddressInfo } from 'node:net';\n\nimport { validationError } from './errors';\n\n/**\n * The \"little GUI\" for a secret: a one-shot form served by the CLI itself on\n * this computer, for a run with no terminal to type into (a coding agent, a\n * script) but a person at the desktop. The person types the secret into\n * their own browser; it goes from there to this process and on to the host,\n * and never to stdout, stderr, a log or the `--json` envelope — so an agent\n * driving the CLI starts the form and never sees what was entered.\n *\n * What keeps it to that one person and that one submission:\n *\n *  - **Loopback only.** It listens on 127.0.0.1, on a port the OS picks.\n *  - **An unguessable path.** 256 random bits; any other path is a 404.\n *  - **Host and Origin.** A request whose `Host` is not exactly\n *    `127.0.0.1:<port>` is refused (a DNS-rebinding page names its own\n *    host), and a submission must carry this form's `Origin` — so another\n *    page in the same browser cannot post to it.\n *  - **One use, short life.** The first good submission closes the server;\n *    so does the timeout, which fails the command rather than waiting on.\n *  - **A page that loads nothing.** No script, no external asset: a CSP of\n *    `default-src 'none'` with one nonce'd stylesheet, never framed, never\n *    cached, no referrer.\n */\n\nexport interface SecretFormField {\n  name: string;\n  label: string;\n  sensitive: boolean;\n  description?: string;\n  required?: boolean;\n  /** A value is saved already: leaving it empty keeps it. */\n  set?: boolean;\n  /** A non-secret field's saved value, shown as the placeholder. Never a secret. */\n  value?: string | null;\n}\n\nexport interface SecretFormOptions {\n  title: string;\n  fields: readonly SecretFormField[];\n  /** Opens the form's URL in the person's browser. */\n  open: (url: string) => void;\n  /** How long to wait for the submission (default five minutes). */\n  timeoutMs?: number;\n}\n\nexport const SECRET_FORM_TIMEOUT_MS = 5 * 60 * 1000;\nconst MAX_BODY_BYTES = 64 * 1024;\n\n/**\n * Serve the form, open it, and resolve with what was submitted: each field's\n * value by name, empty ones left out. Rejects on the timeout.\n */\nexport function collectWithSecretForm(\n  options: SecretFormOptions,\n): Promise<Record<string, string>> {\n  const token = randomBytes(32).toString('base64url');\n  const nonce = randomBytes(16).toString('base64');\n  const timeoutMs = options.timeoutMs ?? SECRET_FORM_TIMEOUT_MS;\n\n  return new Promise((resolve, reject) => {\n    let settled = false;\n    let origin = '';\n    let hostHeader = '';\n\n    const server = http.createServer((request, response) => {\n      handle(request, response).catch(() => {\n        if (!response.headersSent)\n          send(\n            response,\n            500,\n            page('Something went wrong', 'Return to your terminal.'),\n          );\n      });\n    });\n\n    const finish = (outcome: () => void) => {\n      if (settled) return;\n      settled = true;\n      clearTimeout(timer);\n      server.close();\n      server.closeAllConnections();\n      outcome();\n    };\n\n    const timer = setTimeout(() => {\n      finish(() =>\n        reject(\n          validationError(\n            `The secure form was not submitted within ${duration(timeoutMs)}; nothing was saved.`,\n            'Run the command again for a fresh form, or pass the secret with --secret-env, --secret-file or --secret-stdin.',\n          ),\n        ),\n      );\n    }, timeoutMs);\n\n    const send = (\n      response: http.ServerResponse,\n      status: number,\n      body: string,\n    ) => {\n      response.writeHead(status, {\n        'content-type': 'text/html; charset=utf-8',\n        'cache-control': 'no-store',\n        'content-security-policy': `default-src 'none'; style-src 'nonce-${nonce}'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'`,\n        'x-frame-options': 'DENY',\n        'x-content-type-options': 'nosniff',\n        'referrer-policy': 'no-referrer',\n        'cross-origin-resource-policy': 'same-origin',\n      });\n      response.end(body);\n    };\n\n    const page = (heading: string, text: string, inner = '') =>\n      [\n        '<!doctype html>',\n        '<html lang=\"en\"><head><meta charset=\"utf-8\">',\n        '<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">',\n        '<meta name=\"referrer\" content=\"no-referrer\">',\n        `<title>${escapeHtml(heading)} · ekanos</title>`,\n        `<style nonce=\"${nonce}\">${STYLE}</style>`,\n        '</head><body><main>',\n        `<h1>${escapeHtml(heading)}</h1>`,\n        `<p class=\"lede\">${escapeHtml(text)}</p>`,\n        inner,\n        '</main></body></html>',\n      ].join('');\n\n    const isOurPath = (pathname: string): boolean => {\n      const expected = Buffer.from(`/${token}`);\n      const given = Buffer.from(pathname);\n      return (\n        given.length === expected.length && timingSafeEqual(given, expected)\n      );\n    };\n\n    async function handle(\n      request: http.IncomingMessage,\n      response: http.ServerResponse,\n    ): Promise<void> {\n      if (settled) {\n        send(\n          response,\n          410,\n          page('This form is closed', 'Return to your terminal.'),\n        );\n        return;\n      }\n      if (request.headers.host !== hostHeader) {\n        send(\n          response,\n          421,\n          page('Wrong address', 'Open the link the ekanos CLI opened.'),\n        );\n        return;\n      }\n      const pathname = (request.url ?? '').split('?')[0] ?? '';\n      if (!isOurPath(pathname)) {\n        send(\n          response,\n          404,\n          page('Not found', 'Open the link the ekanos CLI opened.'),\n        );\n        return;\n      }\n\n      if (request.method === 'GET') {\n        send(response, 200, formPage());\n        return;\n      }\n      if (request.method !== 'POST') {\n        response.setHeader('allow', 'GET, POST');\n        send(response, 405, page('Not allowed', 'Return to your terminal.'));\n        return;\n      }\n\n      const fetchSite = request.headers['sec-fetch-site'];\n      if (\n        request.headers.origin !== origin ||\n        (fetchSite !== undefined && fetchSite !== 'same-origin')\n      ) {\n        send(\n          response,\n          403,\n          page('Refused', 'This form only accepts what is typed into it.'),\n        );\n        return;\n      }\n      if (\n        !(request.headers['content-type'] ?? '')\n          .toLowerCase()\n          .startsWith('application/x-www-form-urlencoded')\n      ) {\n        send(response, 415, page('Refused', 'Submit the form itself.'));\n        return;\n      }\n\n      const body = await readBody(request);\n      if (body === null) {\n        send(response, 413, page('Too large', 'Return to your terminal.'));\n        return;\n      }\n      const params = new URLSearchParams(body);\n      const values: Record<string, string> = {};\n      options.fields.forEach((field, index) => {\n        const value = (params.get(`f${index}`) ?? '').trim();\n        if (value) values[field.name] = value;\n      });\n\n      send(\n        response,\n        200,\n        page(\n          'Received',\n          'The ekanos CLI has what you entered and is saving it. You can close this tab and return to your terminal.',\n        ),\n      );\n      finish(() => resolve(values));\n    }\n\n    function formPage(): string {\n      const inputs = options.fields\n        .map((field, index) => {\n          const id = `f${index}`;\n          const placeholder = field.sensitive\n            ? field.set\n              ? 'Saved — leave empty to keep it'\n              : ''\n            : field.set\n              ? field.value\n                ? `Current: ${field.value} — leave empty to keep it`\n                : 'Saved — leave empty to keep it'\n              : '';\n          const required = field.required && !field.set;\n          return [\n            '<div class=\"field\">',\n            `<label for=\"${id}\">${escapeHtml(field.label)}${required ? '' : ' <span class=\"optional\">(optional)</span>'}</label>`,\n            field.description\n              ? `<p class=\"help\" id=\"${id}-help\">${escapeHtml(field.description)}</p>`\n              : '',\n            `<input id=\"${id}\" name=\"${id}\" type=\"${field.sensitive ? 'password' : 'text'}\"`,\n            ' autocomplete=\"off\" autocapitalize=\"off\" spellcheck=\"false\"',\n            placeholder ? ` placeholder=\"${escapeHtml(placeholder)}\"` : '',\n            field.description ? ` aria-describedby=\"${id}-help\"` : '',\n            required ? ' required' : '',\n            index === 0 ? ' autofocus' : '',\n            '>',\n            '</div>',\n          ].join('');\n        })\n        .join('');\n      return page(\n        options.title,\n        'This page is served by the ekanos CLI on your own computer. What you enter goes only to it, then to Ekanos over HTTPS — never to your terminal, a log or the agent that ran the command. It works once and closes.',\n        `<form method=\"post\" action=\"/${token}\">${inputs}<button type=\"submit\">Save</button></form>`,\n      );\n    }\n\n    server.on('error', (error) => finish(() => reject(error)));\n    server.listen(0, '127.0.0.1', () => {\n      const { port } = server.address() as AddressInfo;\n      origin = `http://127.0.0.1:${port}`;\n      hostHeader = `127.0.0.1:${port}`;\n      try {\n        options.open(`${origin}/${token}`);\n      } catch {\n        // The timeout still ends the wait.\n      }\n    });\n  });\n}\n\nfunction readBody(request: http.IncomingMessage): Promise<string | null> {\n  return new Promise((resolve, reject) => {\n    const chunks: Buffer[] = [];\n    let size = 0;\n    let tooLarge = false;\n    request.on('data', (chunk: Buffer) => {\n      size += chunk.length;\n      if (size > MAX_BODY_BYTES) {\n        tooLarge = true;\n        return;\n      }\n      chunks.push(chunk);\n    });\n    request.on('end', () =>\n      resolve(tooLarge ? null : Buffer.concat(chunks).toString('utf8')),\n    );\n    request.on('error', reject);\n  });\n}\n\nfunction duration(ms: number): string {\n  if (ms < 60_000) {\n    const seconds = Math.max(1, Math.ceil(ms / 1000));\n    return `${seconds} second${seconds === 1 ? '' : 's'}`;\n  }\n  const minutes = Math.round(ms / 60_000);\n  return `${minutes} minute${minutes === 1 ? '' : 's'}`;\n}\n\nexport function escapeHtml(value: string): string {\n  return value\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;')\n    .replace(/'/g, '&#39;');\n}\n\nconst STYLE = [\n  ':root{color-scheme:light dark;font-family:ui-sans-serif,system-ui,-apple-system,\"Segoe UI\",sans-serif;line-height:1.5}',\n  'body{margin:0;display:flex;justify-content:center;padding:48px 16px}',\n  'main{width:100%;max-width:440px}',\n  'h1{font-size:1.25rem;margin:0 0 8px}',\n  '.lede{margin:0 0 24px;opacity:.75;font-size:.9rem}',\n  '.field{margin:0 0 16px}',\n  'label{display:block;font-weight:600;font-size:.9rem;margin:0 0 4px}',\n  '.optional{font-weight:400;opacity:.6}',\n  '.help{margin:0 0 6px;font-size:.85rem;opacity:.7}',\n  'input{box-sizing:border-box;width:100%;padding:8px 10px;font:inherit;border:1px solid #8888;border-radius:6px;background:transparent;color:inherit}',\n  'button{margin-top:8px;padding:8px 16px;font:inherit;font-weight:600;border:1px solid currentColor;border-radius:6px;background:transparent;color:inherit;cursor:pointer}',\n].join('');\n"]}

package/dist/secret-input.d.ts

@@ -0,0 +1,96 @@
+import type { CliContext } from './context.js';
+import { type SecretFormField } from './secret-form.js';
+/**
+ * How every command that takes a secret gets it — `apps set`, `apps
+ * connect`, `teams app set`, `teams connect`, `teams mcp token|add`,
+ * `teams llm-key set` — so a coding agent or a script can run them as well
+ * as a person at a terminal, and none of them ever has the secret in argv.
+ *
+ * In order:
+ *
+ *  1. **`--browser`**: a one-shot form on this computer (`secret-form.ts`).
+ *     The person types it in their browser; the run that asked never sees it.
+ *  2. **A named source**: `--secret-env NAME`, `--secret-file PATH` (a
+ *     0600 file of yours, never through a symlink) or `--secret-stdin` (piped)
+ *     for the one secret; `--set-secret <field>=env:NAME|file:PATH|stdin` for
+ *     each field of a form. Nothing else is asked.
+ *  3. **A terminal**: hidden input, as before.
+ *  4. Otherwise a usage error naming the forms above.
+ *
+ * A literal (`--set-secret field=sk-…`) is refused: argv lands in shell
+ * history and the process list. No error, log or output here ever carries a
+ * value — not even a path or a name that might be one by mistake.
+ *
+ * `--browser` is never chosen for you. A run with no terminal is usually an
+ * agent or CI, and the CLI cannot tell whether anyone is at the desktop: a
+ * form nobody fills would stall the run for its whole timeout. So it is
+ * explicit, refused up front where it cannot work (CI, SSH, no display),
+ * and bounded by a timeout everywhere.
+ */
+export interface SecretFlags {
+    /** `--secret-stdin` */
+    stdin: boolean;
+    /** `--secret-env <NAME>` */
+    env?: string;
+    /** `--secret-file <path>` */
+    file?: string;
+    /** `--set-secret <field>=env:NAME|file:PATH|stdin`, repeatable. */
+    sets: string[];
+    /** `--browser` */
+    browser: boolean;
+}
+/** The flags, from a command's parsed flags. */
+export declare function readSecretFlags(flags: Record<string, string | boolean | string[]> | undefined): SecretFlags;
+/** Whether any way of giving a secret without a terminal was passed. */
+export declare function secretInputGiven(flags: SecretFlags): boolean;
+/** The forms, as a hint names them. */
+export declare const SINGLE_SECRET_FORMS = "--secret-env <NAME>, --secret-file <path> (a file only you can read), --secret-stdin (piped in), or --browser (a form in your browser on this computer)";
+export declare const FIELD_SECRET_FORMS = "--set-secret <field>=env:<NAME>|file:<path>|stdin for each secret (--secret-env, --secret-file or --secret-stdin when there is one), or --browser (a form in your browser on this computer)";
+export interface SecretIO {
+    env: Record<string, string | undefined>;
+    stdinIsTTY: boolean;
+    /** Test seam: the whole of stdin. */
+    readStdin?: () => Promise<string>;
+    /** Test seam: the browser opener for `--browser`. */
+    openUrl?: (url: string) => void;
+    /** Test seam: how long `--browser` waits. */
+    formTimeoutMs?: number;
+    /** Test seam: the platform `--browser` checks for a desktop. */
+    platform?: NodeJS.Platform;
+    /** Where a relative `--secret-file` resolves (default: the working directory). */
+    cwd?: string;
+}
+export type SecretField = SecretFormField;
+export interface CollectSecretsInput {
+    /** Every field this run would ask, in order. */
+    fields: readonly SecretField[];
+    flags: SecretFlags;
+    io: SecretIO;
+    /** A human at a terminal (not `--json`, stdin a TTY). */
+    interactive: boolean;
+    /** The terminal question for one field — hidden for a secret. */
+    prompt: (field: SecretField) => Promise<string>;
+    /** The secure form's heading. */
+    title: string;
+    /** What is needed, when nothing can be asked: the refusal's message. */
+    refusal: string;
+    /** The command, without `npx @ekanos/cli`, for hints. */
+    again: string;
+    /**
+     * `--set <field>=<value>` for a field that is not a secret (a subdomain, a
+     * client ID): taken as given, and never asked. A secret here is refused.
+     */
+    plain?: Record<string, string>;
+}
+/**
+ * `--set <field>=<value>` pairs. A malformed one is refused without echoing
+ * it — it may be a secret typed where a field name was meant.
+ */
+export declare function parsePlainValues(raw: string | boolean | string[] | undefined, example?: string): Record<string, string>;
+/**
+ * Each field's value by name; a field left empty is left out (its saved
+ * value stays). Refuses a required field that is neither saved nor given.
+ */
+export declare function collectSecrets(ctx: CliContext, input: CollectSecretsInput): Promise<Record<string, string>>;
+/** Why a browser form cannot be filled here, or null when it can. */
+export declare function desktopProblem(env: Record<string, string | undefined>, platform: NodeJS.Platform): string | null;