@antasphere/chassis-cli 0.0.0-stage → 1.0.1

package/src/index.ts

@@ -0,0 +1,70 @@
+import type { ChassisClient } from '@antasphere/chassis-sdk';
+import { createConfig } from './config.js';
+import { createContext } from './context.js';
+import type { Cli, CliDefinition, CliKit } from './kit.js';
+import { createProgram } from './program.js';
+import { createWorkspace } from './workspace.js';
+
+/**
+ * `@antasphere/chassis-cli`: the generic half of a tool's command line. The
+ * profiles and the config file, the context (instance, key, workspace), the
+ * workspace selection, secrets on stdin, the contained writes, the browser
+ * opener, the generic command groups, the program and the runner. A tool
+ * instantiates it ONCE (`defineCli`) with its identity and its client, and
+ * its command modules read the kit that comes back.
+ */
+
+export { cliIdentity, type CliIdentity } from './identity.js';
+export { redactKey, type CliConfigStore } from './config.js';
+export type { CliConfig, CliConnectKey, CliEnv, CliProfile } from './config.js';
+export {
+  CliUsageError,
+  fmtBytes,
+  printJson,
+  sanitizeForTty,
+  setStdinApiKey,
+  stdinApiKey,
+  table,
+  ttySafeIo,
+  type CliContext,
+  type CliContextKit,
+  type CliIo,
+  type CredentialSource
+} from './context.js';
+export {
+  findWorkspace,
+  isWorkspaceId,
+  matchWorkspace,
+  workspaceLines,
+  type CliWorkspace,
+  type MeResponse,
+  type MeWorkspace,
+  type SelectionKind,
+  type WorkspaceSelection,
+  type WorkspaceSource
+} from './workspace.js';
+export { readSecretFromStdin } from './stdin.js';
+export {
+  resolveInside,
+  streamContained,
+  UnsafeWriteError,
+  writeContained,
+  writeNoFollow
+} from './safe-write.js';
+export { isInteractive, openInBrowser, platformOpener } from './open.js';
+
+export { safeDownloadName } from './commands/files.js';
+export { explainProjectRefusal, roleNamedBy, memberRef, type ProjectLookup } from './commands/projects.js';
+export { CliApiRefusal, drainPages } from './context.js';
+export type { Cli, CliDefinition, CliKit, RegisterTool } from './kit.js';
+
+export function defineCli<TClient extends ChassisClient<string>>(
+  definition: CliDefinition<TClient>
+): Cli<TClient> {
+  const { identity, createClient } = definition;
+  const config = createConfig(identity);
+  const workspace = createWorkspace(identity);
+  const context = createContext({ identity, createClient, config, workspace });
+  const kit: CliKit<TClient> = { identity, createClient, ...config, workspace, ...context };
+  return { ...kit, ...createProgram(kit, definition) };
+}

package/src/kit.ts

@@ -0,0 +1,50 @@
+import type { CliAuthError } from '@antasphere/cli-core';
+import type { ChassisClient, ClientOptions, PlatformApiError } from '@antasphere/chassis-sdk';
+import type { Command } from 'commander';
+import type { CliConfigStore } from './config.js';
+import type { CliContextKit, CliIo } from './context.js';
+import type { CliIdentity } from './identity.js';
+import type { CliWorkspace } from './workspace.js';
+
+/** The tool's hook in the command tree: it registers its own groups on the program. */
+export type RegisterTool = (program: Command, io: CliIo) => void;
+
+export interface CliDefinition<TClient extends ChassisClient<string>> {
+  /** What the tool is called, everywhere the generic CLI spells it (identity.ts). */
+  identity: CliIdentity;
+  /** The program's one-line description (`--help`'s first line after the usage). */
+  description: string;
+  /** The tool's client: every place the generic CLI builds one goes through this. */
+  createClient: (options: ClientOptions) => TClient;
+  /**
+   * The tool's own hint for a refused request, as it is appended to the error
+   * line (leading space and parentheses included), or undefined for none. The
+   * runner asks after the 403 hint and before the 401 one.
+   */
+  errorHint?: (e: PlatformApiError | CliAuthError) => string | undefined;
+}
+
+/** The generic functions bound to one tool, as the command modules read them. */
+export interface CliKit<TClient extends ChassisClient<string>>
+  extends CliConfigStore, CliContextKit<TClient> {
+  identity: CliIdentity;
+  createClient: (options: ClientOptions) => TClient;
+  /** The workspace functions that spell the tool (workspace.ts). */
+  workspace: CliWorkspace;
+}
+
+/** What `defineCli` hands back: the kit, plus the program and the runner. */
+export interface Cli<TClient extends ChassisClient<string>> extends CliKit<TClient> {
+  /**
+   * The command tree, built once per run: the global options, the auth,
+   * workspace, project and demo groups, THE TOOL'S GROUPS, then
+   * instance/export/files, and the completion command last (it prints the
+   * tree, so it must see all of it).
+   */
+  buildProgram(io: CliIo, registerTool: RegisterTool, version: string): Command;
+  /**
+   * Run the CLI with injected I/O and return a process exit code. The bin calls
+   * this with real process streams; tests call it in-process.
+   */
+  run(argv: string[], rawIo: CliIo, registerTool: RegisterTool, version: string): Promise<number>;
+}

package/src/open.ts

@@ -0,0 +1,48 @@
+import { spawn } from 'node:child_process';
+import type { CliIo } from './context.js';
+
+/**
+ * Opening a URL in the person's default browser (PRDCT-2280): the first push
+ * of a folder opens the pushed resource's page, the tool's `open` command opens
+ * it on demand, its `dev` command opens the local preview.
+ *
+ * The URL is always ONE argv item handed to the platform's opener binary,
+ * never a string a shell interprets: a resource title or an instance URL is
+ * somebody else's text, and `sh -c "open $url"` would run whatever it
+ * carries. On Windows `start` is a cmd.exe builtin that `spawn` cannot run
+ * without a shell, so the URL handler is invoked through `rundll32`
+ * instead, which is a real executable taking the URL as an argument.
+ */
+export function platformOpener(platform: NodeJS.Platform = process.platform): {
+  command: string;
+  args: string[];
+} {
+  if (platform === 'darwin') return { command: 'open', args: [] };
+  if (platform === 'win32') return { command: 'rundll32', args: ['url.dll,FileProtocolHandler'] };
+  return { command: 'xdg-open', args: [] };
+}
+
+/**
+ * Best effort: a missing opener (a headless box) must never fail the
+ * command that already did its real work. The runner can inject `io.openUrl`
+ * (tests record the call; nothing is spawned).
+ */
+export function openInBrowser(io: CliIo, url: string, spawnImpl: typeof spawn = spawn): void {
+  if (io.openUrl) {
+    io.openUrl(url);
+    return;
+  }
+  const { command, args } = platformOpener();
+  try {
+    const child = spawnImpl(command, [...args, url], { stdio: 'ignore', detached: true });
+    child.on('error', () => undefined);
+    child.unref();
+  } catch {
+    // best-effort
+  }
+}
+
+/** A stdout that is a terminal: the only place a browser may pop up unasked. */
+export function isInteractive(io: CliIo): boolean {
+  return io.out.isTTY === true;
+}

package/src/owner-session.ts

@@ -0,0 +1,152 @@
+import { ChassisClient, DEFAULT_TIMEOUT_MS } from '@antasphere/chassis-sdk';
+import { CliApiRefusal, CliUsageError, type CliContext } from './context.js';
+import type { CliIdentity } from './identity.js';
+import { readSecretFromStdin } from './stdin.js';
+import { isWorkspaceId, matchWorkspace } from './workspace.js';
+
+/**
+ * A command that acts as a SIGNED-IN OWNER, never with an API key.
+ *
+ * Some owner acts are refused to every machine credential by design (the
+ * demo pass routes: nothing in the scope allowlist opens them, and the
+ * handler checks `via === 'session'` again). The CLI reaches them the way a
+ * browser does: one password sign-in, the session cookie held in memory for
+ * the length of the command, a sign-out when it ends, success or failure.
+ *
+ * The address comes from `--owner-email` or `<PREFIX>_OWNER_EMAIL`, the
+ * password from `<PREFIX>_OWNER_PASSWORD` or, with `--owner-password-stdin`,
+ * the first line of stdin. There is no password flag: a value on the command
+ * line is visible in `ps` and lands in the shell history. None of the three
+ * (address, password, cookie) is ever written to the profile, a file, a log
+ * or the terminal: they live in this function's locals and in the one
+ * client's header map, and die with the command.
+ */
+
+export interface OwnerSessionOptions {
+  /** The tool's identity: `<PREFIX>_OWNER_EMAIL` / `<PREFIX>_OWNER_PASSWORD` are built from it. */
+  identity: Pick<CliIdentity, 'envPrefix'>;
+  /** `--owner-email`. */
+  ownerEmail?: string;
+  /** `--owner-password-stdin`. */
+  ownerPasswordStdin?: boolean;
+}
+
+/**
+ * The sign-in library allows three sign-ins per ten seconds per address, and
+ * a script that makes links for several people signs in once per command:
+ * the fourth command in a row meets the wall. It is a wall of seconds, so the
+ * command waits it out, three times at most, and says so on stderr.
+ */
+const SIGN_IN_WAITS_MS = [4_000, 8_000, 12_000] as const;
+
+/** The session cookie the sign-in library sets, whatever prefix the instance gives it. */
+const SESSION_COOKIE = /session_token$/;
+
+/** `name=value` of the session cookie among the answer's `set-cookie` lines, or null. */
+function sessionCookie(res: Response): string | null {
+  for (const line of res.headers.getSetCookie()) {
+    const pair = line.split(';', 1)[0]!.trim();
+    const eq = pair.indexOf('=');
+    if (eq > 0 && SESSION_COOKIE.test(pair.slice(0, eq))) return pair;
+  }
+  return null;
+}
+
+/** The sign-in library's own refusals are `{ code, message }`; the API's are `{ error: {…} }`. */
+async function refusalMessage(res: Response): Promise<string | null> {
+  const body = (await res.json().catch(() => null)) as {
+    message?: unknown;
+    error?: { message?: unknown };
+  } | null;
+  const message = body?.error?.message ?? body?.message;
+  return typeof message === 'string' && message ? message : null;
+}
+
+async function ownerCredentials(
+  ctx: CliContext,
+  options: OwnerSessionOptions
+): Promise<{ email: string; password: string }> {
+  const { envPrefix } = options.identity;
+  const emailVar = `${envPrefix}_OWNER_EMAIL`;
+  const passwordVar = `${envPrefix}_OWNER_PASSWORD`;
+  const email = (options.ownerEmail ?? ctx.io.env[emailVar] ?? '').trim();
+  const password = options.ownerPasswordStdin
+    ? await readSecretFromStdin(ctx.io, 'owner password')
+    : (ctx.io.env[passwordVar] ?? '');
+  if (!email || !password) {
+    throw new CliUsageError(
+      `This command signs in as an owner of the workspace, never with an API key. Set ${emailVar} ` +
+        `(or pass --owner-email) and ${passwordVar} (or pipe it with --owner-password-stdin).`
+    );
+  }
+  return { email, password };
+}
+
+/**
+ * Sign in as the owner, run `run` with a client that carries the session
+ * cookie and the origin (and no authorization header), then sign out.
+ */
+export async function withOwnerSession<T>(
+  ctx: CliContext,
+  options: OwnerSessionOptions,
+  run: (client: ChassisClient<string>) => Promise<T>
+): Promise<T> {
+  const base = ctx.baseUrl.replace(/\/+$/, '');
+  const origin = new URL(base).origin;
+  const fetchImpl = ctx.io.fetch ?? globalThis.fetch.bind(globalThis);
+  const { email, password } = await ownerCredentials(ctx, options);
+
+  // The server refuses a sign-in that carries no Origin (the cross-site guard).
+  const signIn = () =>
+    fetchImpl(`${base}/api/v1/auth/sign-in/email`, {
+      method: 'POST',
+      headers: { origin, 'content-type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+      signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
+    });
+  const sleep = ctx.io.sleep ?? ((ms: number) => new Promise<void>((done) => setTimeout(done, ms)));
+  let res = await signIn();
+  for (const wait of SIGN_IN_WAITS_MS) {
+    if (res.status !== 429) break;
+    ctx.io.err.write(`The instance limits sign-ins: waiting ${wait / 1000} seconds.\n`);
+    await sleep(wait);
+    res = await signIn();
+  }
+  if (res.status === 429) {
+    throw new CliApiRefusal('Too many sign-in attempts for now: wait a few minutes, then try again.', 429);
+  }
+  if (!res.ok) {
+    const message = (await refusalMessage(res)) ?? `The sign-in failed (HTTP ${res.status}).`;
+    throw new CliApiRefusal(message, res.status);
+  }
+  const answer = (await res.json().catch(() => null)) as { twoFactorRedirect?: unknown } | null;
+  if (answer?.twoFactorRedirect === true) {
+    throw new CliUsageError('This owner has a second factor: mint demo links from the dashboard.');
+  }
+  const cookie = sessionCookie(res);
+  if (!cookie) throw new CliUsageError('The instance answered the sign-in without a session.');
+
+  const headers = { cookie, origin };
+  const client = new ChassisClient<string>({ baseUrl: base, fetch: fetchImpl, headers });
+  try {
+    // The workspace selection applies here as it does to every command
+    // (context.ts `applyWorkspace`): an id as it is, a name through `/me`.
+    const selection = ctx.workspaceSelection;
+    if (selection) {
+      client.setWorkspace(
+        isWorkspaceId(selection.value)
+          ? selection.value
+          : matchWorkspace((await client.me()).workspaces, selection.value).id
+      );
+    }
+    return await run(client);
+  } finally {
+    // The session ends with the command; its outcome changes nothing.
+    await fetchImpl(`${base}/api/v1/auth/sign-out`, {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: '{}',
+      signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
+    }).catch(() => undefined);
+  }
+}

package/src/program.ts

@@ -0,0 +1,183 @@
+import { Command, CommanderError } from 'commander';
+import { CliAuthError, CliConnectError } from '@antasphere/cli-core';
+import { PlatformApiError, type ChassisClient } from '@antasphere/chassis-sdk';
+import { CliApiRefusal, CliUsageError, setStdinApiKey, ttySafeIo, type CliIo } from './context.js';
+import type { Cli, CliDefinition, CliKit, RegisterTool } from './kit.js';
+import { readSecretFromStdin } from './stdin.js';
+import { registerAuthCommands } from './commands/auth.js';
+import { registerWorkspaceCommands } from './commands/workspaces.js';
+import { registerProjectCommands } from './commands/projects.js';
+import { registerTeamCommands } from './commands/teams.js';
+import { registerDemoCommands } from './commands/demo.js';
+import { registerFileCommands } from './commands/files.js';
+import { registerCompletionCommand } from './commands/completion.js';
+
+/** The price and the balance of a credit refusal, each only when it is a number (the code review). */
+function creditFigures(credit: { credits?: unknown; balance?: unknown } | undefined): string {
+  const parts = [
+    typeof credit?.credits === 'number' ? `this needs ${credit.credits} credits` : null,
+    typeof credit?.balance === 'number' ? `the organization holds ${credit.balance}` : null
+  ].filter((x): x is string => x !== null);
+  return parts.length > 0 ? `${parts.join(' and ')}; ` : '';
+}
+
+/** The program and the runner of one tool, over its kit (kit.ts). */
+export function createProgram<TClient extends ChassisClient<string>>(
+  kit: CliKit<TClient>,
+  definition: Pick<CliDefinition<TClient>, 'description' | 'errorHint'>
+): Pick<Cli<TClient>, 'buildProgram' | 'run'> {
+  const { identity, explainWorkspaceRefusal, workspaceNotFoundHint } = kit;
+  const { description, errorHint } = definition;
+
+  function buildProgram(io: CliIo, registerTool: RegisterTool, version: string): Command {
+    const program = new Command();
+    program
+      .name(identity.bin)
+      .description(description)
+      .version(version)
+      .option(
+        '--api-url <url>',
+        `instance base URL (or ${identity.envPrefix}_URL / the profile's; default: the cloud, ${identity.cloudUrl})`
+      )
+      .option('--url <url>', 'alias of --api-url')
+      .option('--api-key <key>', `API key (or ${identity.envPrefix}_API_KEY / profile apiKey)`)
+      .option(
+        '--api-key-stdin',
+        'read the API key from the first line of stdin (keeps it out of argv)',
+        false
+      )
+      .option('--profile <name>', 'use this saved profile (an instance) instead of the active one')
+      .option(
+        '--org <id-or-name>',
+        `run in this Antasphere organization, by its id or name (or ${identity.envPrefix}_ORG; default: your default organization)`
+      )
+      .option(
+        '--workspace <id-or-name>',
+        `run in this workspace of the instance, by its id or name (or ${identity.envPrefix}_WORKSPACE; default: the server's)`
+      )
+      .option('--json', 'machine-readable JSON output', false);
+
+    // Identity + profiles: login, logout, whoami, verify, use, profiles,
+    // config show/clear.
+    registerAuthCommands(kit, program, io);
+    // Which workspace the commands run in: workspaces, workspace default.
+    registerWorkspaceCommands(kit, program, io);
+    // The subgroups of the workspace: projects *, projects members *.
+    registerProjectCommands(kit, program, io);
+    // The named groups of the workspace's people: teams *.
+    registerTeamCommands(kit, program, io);
+    // Demo links, as a signed-in owner (never a key): demo link, list, revoke.
+    registerDemoCommands(kit, program, io);
+    // The tool's own groups, where they have always sat in `--help`.
+    registerTool(program, io);
+    // Platform substrate (template heritage): instance, export, files *.
+    registerFileCommands(kit, program, io);
+    // Shell completion — registered LAST so the tree it prints is complete.
+    registerCompletionCommand(identity, program, io);
+
+    return program;
+  }
+
+  async function run(
+    argv: string[],
+    rawIo: CliIo,
+    registerTool: RegisterTool,
+    version: string
+  ): Promise<number> {
+    // Every human sink is wrapped ONCE, here: resource titles, annotation bodies,
+    // stored filenames and server error messages are all somebody else's text
+    // heading for a terminal (context.ts `sanitizeForTty`). `--json` keeps the
+    // raw sink through `printJson`.
+    const io = ttySafeIo(rawIo);
+
+    // `--api-key-stdin` is resolved BEFORE commander parses: `resolveContext`
+    // is synchronous, so the key must already be parked against this io by
+    // the time a command asks for it. Reading stdin is the whole point — an
+    // argv-borne secret is visible in `ps` and lands in the shell history.
+    if (argv.includes('--api-key-stdin')) {
+      try {
+        setStdinApiKey(io, await readSecretFromStdin(io, 'API key'));
+      } catch (e) {
+        io.err.write(`Error: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+      }
+    }
+
+    const program = buildProgram(io, registerTool, version);
+    program.exitOverride();
+    program.configureOutput({
+      writeOut: (s) => io.out.write(s),
+      writeErr: (s) => io.err.write(s)
+    });
+    try {
+      await program.parseAsync(argv, { from: 'user' });
+      return 0;
+    } catch (e) {
+      if (e instanceof CommanderError) {
+        // --help / --version and usage errors already wrote their output.
+        return e.exitCode;
+      }
+      if (e instanceof CliConnectError && e.refusal) {
+        // The hub (or the instance's connect door) refused the PERSON, not
+        // the credential: the server's own sentence, as it is, and exit 3,
+        // the code the docs promise for a refusal. No hint: no key fixes it.
+        io.err.write(`Error: ${e.message}\n`);
+        return e.exitCode;
+      }
+      if (e instanceof PlatformApiError || e instanceof CliAuthError) {
+        // A refusal the workspace SELECTION caused reads as a bad key (401) or
+        // a forbidden one (403) on the wire; say what it really was.
+        const explained = await explainWorkspaceRefusal(io, e);
+        if (explained) {
+          io.err.write(`Error: ${explained}\n`);
+          return 1;
+        }
+        // A plan refusal (the billing rail, 403 `plan_required`) is not a
+        // key's fault: the sentence carries the upgrade link, the hub's
+        // organization page, where a human raises the plan.
+        const upgradeUrl = (
+          e instanceof PlatformApiError && e.code === 'plan_required'
+            ? (e.details as { upgradeUrl?: unknown } | undefined)?.upgradeUrl
+            : undefined
+        ) as string | undefined;
+        // A credit refusal (402 `entitlement_denied`, PRDCT-2664) carries the
+        // price, the balance and the top-up link, the hub's billing page. The
+        // self-hosted cap's 413 has no details and keeps its message alone.
+        const credit = (
+          e instanceof PlatformApiError && e.code === 'entitlement_denied' ? e.details : undefined
+        ) as { credits?: unknown; balance?: unknown; topUpUrl?: unknown } | undefined;
+        const topUpUrl = typeof credit?.topUpUrl === 'string' && credit.topUpUrl ? credit.topUpUrl : null;
+        // The gate's own message already spells the price, the balance and
+        // the link; the hint repeats them only for a message that does not
+        // (verifier round 1: the URL was printed twice).
+        const hint =
+          typeof upgradeUrl === 'string' && upgradeUrl
+            ? ` — upgrade the plan at ${upgradeUrl}`
+            : topUpUrl && !e.message.includes(topUpUrl)
+              ? ` — ${creditFigures(credit)}top up at ${topUpUrl}`
+              : e.status === 403
+                ? ' (this API key is not allowed to do that)'
+                : (errorHint?.(e) ??
+                  (e.status === 401
+                    ? ` (check the key: \`${identity.bin} verify\`)`
+                    : e.status === 404
+                      ? workspaceNotFoundHint(io)
+                      : ''));
+        io.err.write(`Error: ${e.message}${hint}\n`);
+        return 1;
+      }
+      if (e instanceof CliUsageError) {
+        // A refusal a command already worded keeps the one thing the command
+        // cannot know: the workspace a 404 was asked of. The thrower says the
+        // exit code (cli-core: 1 a usage or wire error, 3 a refusal).
+        const hint = e instanceof CliApiRefusal && e.status === 404 ? workspaceNotFoundHint(io) : '';
+        io.err.write(`Error: ${e.message}${hint}\n`);
+        return e.exitCode;
+      }
+      io.err.write(`Error: ${e instanceof Error ? e.message : String(e)}\n`);
+      return 1;
+    }
+  }
+
+  return { buildProgram, run };
+}

package/src/safe-write.ts

@@ -0,0 +1,136 @@
+import { constants as FS } from 'node:fs';
+import { mkdir, open, realpath, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import type { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+/**
+ * Writing SERVER-CHOSEN paths to a developer's disk, safely.
+ *
+ * The tool's `pull` and the generic `files download` both materialize names the
+ * instance picked (a manifest path, a stored filename). That makes the local
+ * filesystem the last line of defence, and a lexical `resolve()` +
+ * `startsWith()` is not one: it says nothing about symlinks. Three rules,
+ * enforced here so both call sites get the same ones:
+ *
+ *  1. the path must be relative and stay inside the destination LEXICALLY;
+ *  2. the parent directory, after `realpath()`, must still be inside the
+ *     destination (a symlinked sub-directory is a way out);
+ *  3. the final component is opened `O_NOFOLLOW`, so an existing symlink is
+ *     refused rather than written through, and the file's mode is forced to
+ *     0644 — `O_TRUNC` on an existing file PRESERVES its mode, which is how
+ *     an already-executable path stays executable after a hostile pull.
+ */
+
+/** Thrown when a write target fails containment; the CLI turns it into exit 1. */
+export class UnsafeWriteError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UnsafeWriteError';
+  }
+}
+
+/** Lexical containment: `relPath` must resolve to something under `root`. */
+export function resolveInside(root: string, relPath: string): string {
+  if (isAbsolute(relPath)) {
+    throw new UnsafeWriteError(`Refusing to write an absolute path: ${relPath}`);
+  }
+  const target = resolve(root, relPath);
+  const rel = relative(root, target);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+    throw new UnsafeWriteError(`Refusing to write outside ${root}: ${relPath}`);
+  }
+  return target;
+}
+
+/**
+ * Create (recursively) the parent of `target` and prove that the REAL
+ * directory it lands in is still inside `root`. `mkdir -p` happily walks
+ * through an existing symlinked directory, so this must run after it.
+ */
+async function prepareParent(root: string, target: string): Promise<void> {
+  const parent = dirname(target);
+  await mkdir(parent, { recursive: true });
+  const realRoot = await realpath(root);
+  const realParent = await realpath(parent);
+  const rel = relative(realRoot, realParent);
+  if (rel !== '' && (rel.startsWith('..') || isAbsolute(rel))) {
+    throw new UnsafeWriteError(
+      `Refusing to write through a symlinked directory: ${parent} resolves to ${realParent}, ` +
+        `outside ${realRoot}`
+    );
+  }
+}
+
+/**
+ * Write `bytes` at `root`/`relPath` under all three rules above. Returns the
+ * absolute path written.
+ */
+export async function writeContained(root: string, relPath: string, bytes: Uint8Array): Promise<string> {
+  const target = resolveInside(root, relPath);
+  await prepareParent(root, target);
+  await writeNoFollow(target, bytes);
+  return target;
+}
+
+/**
+ * Write `bytes` to an exact path, refusing to follow a symlink there and
+ * forcing mode 0644 (never inherit an existing file's executable bit).
+ */
+export async function writeNoFollow(target: string, bytes: Uint8Array): Promise<void> {
+  let handle;
+  try {
+    handle = await open(target, FS.O_WRONLY | FS.O_CREAT | FS.O_TRUNC | FS.O_NOFOLLOW, 0o644);
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    // ELOOP (POSIX) / EMLINK (some BSDs) — the target exists and is a symlink.
+    if (code === 'ELOOP' || code === 'EMLINK') {
+      throw new UnsafeWriteError(`Refusing to write through the symlink at ${target}`);
+    }
+    throw e;
+  }
+  try {
+    await handle.writeFile(bytes);
+    // O_TRUNC keeps the existing mode; re-assert it so a pull can never
+    // leave a file executable (or group/world-writable) behind.
+    await handle.chmod(0o644).catch(() => undefined);
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Stream `source` to `root`/`relPath` under the same three rules as
+ * `writeContained`, for a body too large to buffer (a zip of respondent
+ * uploads). Returns the absolute path and the byte count. A failed stream
+ * removes the partial file — a truncated archive must not look like a
+ * finished one.
+ */
+export async function streamContained(
+  root: string,
+  relPath: string,
+  source: Readable
+): Promise<{ path: string; sizeBytes: number }> {
+  const target = resolveInside(root, relPath);
+  await prepareParent(root, target);
+  let handle;
+  try {
+    handle = await open(target, FS.O_WRONLY | FS.O_CREAT | FS.O_TRUNC | FS.O_NOFOLLOW, 0o644);
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === 'ELOOP' || code === 'EMLINK') {
+      throw new UnsafeWriteError(`Refusing to write through the symlink at ${target}`);
+    }
+    throw e;
+  }
+  try {
+    await handle.chmod(0o644).catch(() => undefined);
+    const sink = handle.createWriteStream();
+    await pipeline(source, sink);
+    return { path: target, sizeBytes: sink.bytesWritten };
+  } catch (e) {
+    await handle.close().catch(() => undefined);
+    await unlink(target).catch(() => undefined);
+    throw e;
+  }
+}

package/src/stdin.ts

@@ -0,0 +1,39 @@
+import { CliUsageError, type CliIo } from './context.js';
+
+/**
+ * Secrets that arrive on stdin instead of the command line.
+ *
+ * A value passed as `--api-key <prefix>_…` or `--password hunter2` is visible to
+ * every process on the box (`ps`, `/proc/<pid>/cmdline`) and lands verbatim
+ * in the shell history file. The flags stay — they are what scripts already
+ * use — but each one now has a `-stdin` sibling and, for the share
+ * password, an environment variable, so nothing forces a secret through
+ * argv.
+ *
+ * stdin can only be spent once, so it is claimed: the second claimant in one
+ * invocation gets a usage error instead of silently receiving the first
+ * one's value.
+ */
+
+const claims = new WeakMap<CliIo, string>();
+
+async function readAllStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/** First line of stdin, claimed for exactly one purpose per invocation. */
+export async function readSecretFromStdin(io: CliIo, claimant: string): Promise<string> {
+  const holder = claims.get(io);
+  if (holder !== undefined) {
+    throw new CliUsageError(
+      `Only one secret can be read from stdin per command — ${holder} already claimed it.`
+    );
+  }
+  claims.set(io, claimant);
+  const raw = await (io.readStdin ?? readAllStdin)();
+  const value = raw.split('\n')[0]?.trim() ?? '';
+  if (!value) throw new CliUsageError(`Nothing on stdin to read the ${claimant} from.`);
+  return value;
+}