@knowttl/artium-axi 0.0.2 → 0.0.4

package/README.md

@@ -652,7 +652,7 @@ See the [API contract](src/shared/api.ts) and [retention and export runbook](doc
 | --- | --- |
 | `ARTIUM_AXI_URL` | Required HTTPS base URL without credentials, query or fragment. |
 | `ARTIUM_AXI_CA_FILE` | Optional readable PEM CA file added to Node's certificate trust. |
-| `ARTIUM_AXI_PASSWORD` | Login password source when `--password-stdin` is absent, before the terminal prompt. |
+| `ARTIUM_AXI_PASSWORD` | Ordinary login password source when `--password-stdin` is absent, before the terminal prompt; refused for [managed sign-in](#externally-managed-client-sessions). |
 | `ARTIUM_AXI_CURRENT_PASSWORD` | Current password for an ordinary password change, before the terminal prompt. |
 | `XDG_CONFIG_HOME` | Session-file base on Linux/macOS; otherwise `~/.config`. |
 | `APPDATA` | Session-file base on Windows, whose execution remains unverified. |
@@ -660,11 +660,12 @@ See the [API contract](src/shared/api.ts) and [retention and export runbook](doc
 
 Use `login --password-stdin` or `passwd --password-stdin` to supply the login or new password through stdin.
 Stdin removes one final LF or CRLF and preserves all other spaces and Unicode.
-Password arguments are refused; tokens are never printed.
+Password arguments are refused; tokens are never printed to stdout or stderr.
 Ordinary password changes also require the current password through the terminal prompt or `ARTIUM_AXI_CURRENT_PASSWORD`.
 Clear password environment values after use.
 
-Sessions live in `artium-axi/session.json` under the applicable base directory and are bound to the normalized server URL.
+By default, sessions live in `artium-axi/session.json` under the applicable base directory and are bound to the normalized server URL.
+Callers that manage their own tokens can instead use [externally managed client sessions](#externally-managed-client-sessions).
 POSIX directories use mode 0700 and files mode 0600; Windows uses a restricted ACL and refuses storage if it cannot establish it.
 Do not export or share the session file.
 CLI processes serialize refreshes through `session.lock`; after `SESSION_BUSY`, remove that lock directory only when every CLI process has exited.
@@ -675,6 +676,58 @@ Certificate verification remains enforced even with `NODE_TLS_REJECT_UNAUTHORIZE
 Only an explicit pre-execution `TOKEN_EXPIRED` response permits one serialized refresh and retry.
 A network failure or uncertain command outcome is never retried automatically.
 
+### Externally managed client sessions
+
+Callers that keep credentials outside the CLI can opt in with one leading flag: `artium-axi --managed-session <command> <args>`.
+The caller supplies inherited pipes or sockets: fd 3 for session input on authenticated calls and fd 4 for private new-session and rotation output.
+Stdin remains available for tool input; stdout and stderr retain their normal command formats.
+Do not pass tokens in arguments or environment variables, connect fd 4 to a log or public output, or redirect either private channel to a disk file.
+The CLI refuses regular files as private channels and never reads, creates, locks, updates or deletes `session.json` in this mode.
+
+For authenticated calls, send one UTF-8 JSON object of at most 64 KiB to fd 3, then close the input pipe:
+
+```json
+{"serverUrl":"https://artium.example.test","accessToken":"CANARY-access","refreshToken":"CANARY-refresh"}
+```
+
+`serverUrl` must match the normalized `ARTIUM_AXI_URL`, allowing a final slash.
+`accessToken` is required and nonempty; `refreshToken` is optional and nonempty when supplied.
+The optional fields `status: "authenticated"`, `accessExpiresAt` and `familyExpiresAt` (integer Unix milliseconds) allow a rotation record to be reused as input; other fields are refused.
+The caller owns expiry policy, refresh serialization across processes and secure persistence.
+Managed mode supports `login`, the home view, `whoami`, `tools`, `tools show`, `doctor` and tool commands.
+`passwd`, `logout` and `setup` are refused before any network call; ordinary sign-in and its server-version warning remain unchanged without the flag.
+Help is available without private channels through `artium-axi --help`.
+
+To obtain the first session, run `artium-axi --managed-session login --username <username> --password-stdin` with the password on protected inherited stdin, or `artium-axi --managed-session login --sso` for browser approval.
+Login does not read or require fd 3; it requires a writable private pipe or socket on fd 4 before contacting the server.
+Password arguments and `ARTIUM_AXI_PASSWORD` are refused, including when `--password-stdin` is present; unset that variable before managed sign-in.
+Password input follows the stdin rules in [client settings](#client-settings).
+SSO displays the approval URL and user code immediately so the user can approve while the CLI waits.
+Both sign-in methods return the new session as one newline-terminated JSON object on fd 4, using the same envelope shown below for rotations, and create nothing under the config or session paths.
+The login server-version warning still appears on stderr when versions differ.
+If a local account requires a password change, fd 4 instead receives `{serverUrl, status: "password-change-required", passwordChangeToken, passwordChangeExpiresAt}` and the command returns `PASSWORD_CHANGE_REQUIRED` (exit 1).
+That restricted record is not valid managed-session input; the caller must complete the password change through the server API and sign in again.
+
+Only an explicit `TOKEN_EXPIRED` response permits a single refresh and retry of that request.
+Without a refresh token, or if refresh is refused, the CLI returns the authentication error for the caller to handle.
+Network failures and uncertain outcomes are never automatically retried.
+After a successful refresh, fd 4 receives one newline-terminated JSON object before the request is retried:
+
+```json
+{"serverUrl":"https://artium.example.test","status":"authenticated","accessToken":"CANARY-new-access","refreshToken":"CANARY-new-refresh","accessExpiresAt":1800000000000,"familyExpiresAt":1800003600000}
+```
+
+Every rotation is delivered even if the subsequent request fails; an authenticated invocation without rotation writes no record.
+Consume fd 4 concurrently with stdout and stderr, and retain new sessions and rotations regardless of the command's exit status.
+If new-session or rotation delivery fails, the CLI returns `INVALID_INPUT` (exit 2); the caller must recover the session.
+After failed rotation delivery, the CLI refuses to retry the request; do not reuse the consumed refresh token.
+Managed public output is buffered and scanned against supplied, newly issued and rotated tokens and their canonical encodings before printing; a match withholds both buffered streams and returns `SECRET_IN_OUTPUT`.
+SSO approval instructions are displayed before session issuance; managed password input and the private SSO device code are also checked against buffered output.
+
+Exit codes are 0 for success, 2 for invalid input, client configuration or private channels and refused commands, and 1 for authentication, server-binding, transport or output-scanning failures.
+Tool exit codes pass through as usual.
+Missing or closed descriptors, invalid JSON and mismatched server bindings fail before network access; no failure falls back to a session file.
+
 ### Server settings and custody
 
 | Variable | Meaning |

package/bin/artium-axi.mjs

@@ -4498,9 +4498,9 @@ var $ZodTransform = /* @__PURE__ */ $constructor("$ZodTransform", (inst, def) =>
     }
     const _out = def.transform(payload.value, payload);
     if (ctx.async) {
-      const output2 = _out instanceof Promise ? _out : Promise.resolve(_out);
-      return output2.then((output3) => {
-        payload.value = output3;
+      const output3 = _out instanceof Promise ? _out : Promise.resolve(_out);
+      return output3.then((output4) => {
+        payload.value = output4;
         return payload;
       });
     }
@@ -4950,12 +4950,12 @@ var $ZodFunction = /* @__PURE__ */ $constructor("$ZodFunction", (inst, def) => {
       output: inst._def.output
     });
   };
-  inst.output = (output2) => {
+  inst.output = (output3) => {
     const F = inst.constructor;
     return new F({
       type: "function",
       input: inst._def.input,
-      output: output2
+      output: output3
     });
   };
   return inst;
@@ -18364,14 +18364,14 @@ var ZodTransform = /* @__PURE__ */ $constructor("ZodTransform", (inst, def) => {
         payload.issues.push(util_exports.issue(_issue));
       }
     };
-    const output2 = def.transform(payload.value, payload);
-    if (output2 instanceof Promise) {
-      return output2.then((output3) => {
-        payload.value = output3;
+    const output3 = def.transform(payload.value, payload);
+    if (output3 instanceof Promise) {
+      return output3.then((output4) => {
+        payload.value = output4;
         return payload;
       });
     }
-    payload.value = output2;
+    payload.value = output3;
     return payload;
   };
 });
@@ -20452,7 +20452,7 @@ import { rootCertificates } from "node:tls";
 // package.json
 var package_default = {
   name: "artium-axi",
-  version: "0.0.2",
+  version: "0.0.4",
   private: true,
   license: "MIT",
   type: "module",
@@ -20636,20 +20636,27 @@ var SessionStore = class {
 // src/cli/http.ts
 var DEFAULT_REQUEST_DEADLINE_MS = 9e4;
 var Client = class {
-  constructor(environment = process.env) {
+  constructor(environment = process.env, managed2) {
     this.environment = environment;
+    this.managed = managed2;
     try {
       const url2 = new URL(environment.ARTIUM_AXI_URL);
       if (url2.username || url2.password || url2.href.includes("?") || url2.href.includes("#") || url2.protocol !== "https:" && !(url2.protocol === "http:" && environment.ARTIUM_AXI_TEST_HTTP === "1" && ["localhost", "127.0.0.1", "[::1]"].includes(url2.hostname))) throw new Error();
       this.serverUrl = url2.href.replace(/\/$/, "");
-      this.sessions = new SessionStore(this.serverUrl, sessionPath(process.platform, environment));
+      if (!managed2) this.storedSessions = new SessionStore(this.serverUrl, sessionPath(process.platform, environment));
     } catch {
       throw new ArtiumError("CLIENT_CONFIG_INVALID");
     }
+    managed2?.checkServer(this.serverUrl);
   }
   environment;
+  managed;
   serverUrl;
-  sessions;
+  storedSessions;
+  get sessions() {
+    if (!this.storedSessions) throw new ArtiumError("INVALID_INPUT", "Session-file operations are unavailable in managed mode.");
+    return this.storedSessions;
+  }
   certificateVerified = false;
   async request(path, method, input2, token) {
     this.certificateVerified = false;
@@ -20719,12 +20726,18 @@ var Client = class {
     if (result.status !== 200 && result.status !== 204) throw new ArtiumError("INVALID_RESPONSE");
     if ((path === "/v1/auth/login" || path === "/v1/auth/device") && result.serverVersion && result.serverVersion !== cliVersion) {
       const version2 = result.serverVersion.replace(/[\x00-\x1f\x7f]/g, "");
-      process.stderr.write(`warning: CLI ${cliVersion} differs from server ${version2}; download the matching client from ${this.serverUrl}/cli/artium-axi.mjs and verify its .sha256, or run npm install -g @knowttl/artium-axi@${version2}.
-`);
+      const warning = `warning: CLI ${cliVersion} differs from server ${version2}; download the matching client from ${this.serverUrl}/cli/artium-axi.mjs and verify its .sha256, or run npm install -g @knowttl/artium-axi@${version2}.
+`;
+      if (this.managed) this.managed.write("stderr", warning);
+      else process.stderr.write(warning);
     }
     return result.body;
   }
   async authenticated(path, method, input2, previous) {
+    if (this.managed) return this.managed.authenticated(
+      (token) => this.request(path, method, input2, token),
+      (refreshToken) => this.request("/v1/auth/refresh", "POST", { refreshToken })
+    );
     const session = previous ? this.reload(previous) : this.sessions.read();
     if (!session) throw new ArtiumError("TOKEN_INVALID", void 0, "Run artium-axi login --username <username> --password-stdin.");
     if (session.status === "password-change-required") throw new ArtiumError("PASSWORD_CHANGE_REQUIRED");
@@ -20808,16 +20821,18 @@ async function readPassword(stdin, environmentVariable) {
 }
 
 // src/cli/doctor.ts
-async function doctor() {
+async function doctor(createClient = () => new Client(), write = (text2) => {
+  process.stdout.write(text2);
+}) {
   let failure2;
   const line = (name, pass, detail, error62) => {
     if (!pass) failure2 ??= error62 ?? new ArtiumError("INVALID_RESPONSE");
-    process.stdout.write(`${pass ? "pass" : "fail"}: ${name}${detail ? ` (${detail})` : ""}
+    write(`${pass ? "pass" : "fail"}: ${name}${detail ? ` (${detail})` : ""}
 `);
   };
   let client;
   try {
-    client = new Client();
+    client = createClient();
   } catch (error62) {
     for (const name of ["server address", "certificate", "token", "CLI version"]) line(name, false, "CLIENT_CONFIG_INVALID");
     throw error62;
@@ -22878,7 +22893,14 @@ var commands = {
 };
 function commandHelp(command) {
   const entry = commands[command];
-  const flags = [command === "falcon-axi" || command === "vectra-axi" || command === "ldap-axi" ? "--help before the tool name (default false)" : "--help (default false)", ...entry.flags];
+  const flags = [
+    command === "falcon-axi" || command === "vectra-axi" || command === "ldap-axi" ? "--help before the tool name (default false)" : "--help (default false)",
+    ...entry.flags,
+    "--managed-session before the command (default false; login and authenticated calls; session JSON on inherited pipe fd 3, new sessions and rotations as JSON lines on private pipe fd 4; no session file)",
+    "Managed input: {serverUrl, accessToken, refreshToken?}; close fd 3 after JSON (64 KiB maximum). Output: {serverUrl, status, accessToken, refreshToken, accessExpiresAt, familyExpiresAt} per rotation, before retry, including on later failure.",
+    "Managed login: fd 3 is unused; fd 4 must be a writable private pipe/socket. Local sign-in requires --username <username> --password-stdin with protected inherited stdin; password argv and ARTIUM_AXI_PASSWORD are refused. SSO uses login --sso and displays browser approval instructions immediately. New sessions use the rotation envelope; password-change-required returns {serverUrl, status, passwordChangeToken, passwordChangeExpiresAt} on fd 4 and exits 1.",
+    "Managed exits: 0 success; 2 invalid JSON/descriptors or refused passwd/logout/setup; 1 authentication/transport failure; tool exit codes pass through. Only TOKEN_EXPIRED permits one refresh/retry; without refreshToken or on refusal, return control to the caller."
+  ];
   return `usage: ${entry.usage}
 purpose: ${entry.purpose}
 flags[${flags.length}]:
@@ -33713,25 +33735,25 @@ function rewriteDiscoveryHelp(help, tool) {
     examples: help.examples.map((example) => hostedHelp(example, tool, flags, true))
   });
 }
-function rewriteSuggestions(output2, tool, truncated = false) {
-  if (truncated) return output2;
+function rewriteSuggestions(output3, tool, truncated = false) {
+  if (truncated) return output3;
   const flags = managedFlags[tool];
-  if (!flags) return output2;
+  if (!flags) return output3;
   const executable = new RegExp(`^(?:artium-axi |npx -y @knowttl/)?${tool}(?=\\s|$)`);
-  if (executable.test(output2.replace(/^[ \t]*(?:(?:Command|Native operation|Examples): )?/, "")) || tool === "ldap-axi" && ldapHelp.test(output2)) return hostedHelp(output2, tool, flags, true);
+  if (executable.test(output3.replace(/^[ \t]*(?:(?:Command|Native operation|Examples): )?/, "")) || tool === "ldap-axi" && ldapHelp.test(output3)) return hostedHelp(output3, tool, flags, true);
   let spans;
   let unknownOutcome = false;
   try {
-    const json2 = output2.trimStart().startsWith("{");
-    let parsed = json2 ? jsonHelp(output2) : toonHelp(output2);
+    const json2 = output3.trimStart().startsWith("{");
+    let parsed = json2 ? jsonHelp(output3) : toonHelp(output3);
     if (tool === "ldap-axi" && parsed.document.description === "Read Active Directory and LDAPv3 directories safely with ldap-axi (read-only)" && Array.isArray(parsed.document.commands) && parsed.spans.length) {
       const home = {
         ...parsed.document,
         commands: parsed.document.commands.filter((command) => ldapCommands.includes(command)),
         help: [...parsed.spans.map((span) => span.value).filter((value) => !/^(?:Authentication auto selects|Set LDAP_AXI_URL)/.test(value) && value !== ldapCredentialGuidance), ldapCredentialGuidance]
       };
-      output2 = (json2 ? JSON.stringify(home) : encode3(home)) + "\n";
-      parsed = json2 ? jsonHelp(output2) : toonHelp(output2);
+      output3 = (json2 ? JSON.stringify(home) : encode3(home)) + "\n";
+      parsed = json2 ? jsonHelp(output3) : toonHelp(output3);
     }
     const { spans: suggestions, document } = parsed;
     spans = suggestions;
@@ -33739,15 +33761,15 @@ function rewriteSuggestions(output2, tool, truncated = false) {
       unknownOutcome = document?.code === "UNKNOWN_OUTCOME" || document?.error?.code === "UNKNOWN_OUTCOME";
     }
   } catch {
-    return output2;
+    return output3;
   }
   for (const span of [...spans].reverse()) {
     const value = hostedHelp(span.value, tool, flags, /^[ \t]*(?:Command|Native operation|Examples):/m.test(span.value));
     if (value === span.value) continue;
-    output2 = output2.slice(0, span.start) + (span.quoted || tool === "ldap-axi" && /[,\r\n]/.test(value) ? JSON.stringify(value) : value) + output2.slice(span.start + span.raw.length);
+    output3 = output3.slice(0, span.start) + (span.quoted || tool === "ldap-axi" && /[,\r\n]/.test(value) ? JSON.stringify(value) : value) + output3.slice(span.start + span.raw.length);
   }
-  spans = (output2.trimStart().startsWith("{") ? jsonHelp(output2) : toonHelp(output2)).spans;
-  if (spans.some((span) => /\\[`'"]/.test(span.value))) return output2;
+  spans = (output3.trimStart().startsWith("{") ? jsonHelp(output3) : toonHelp(output3)).spans;
+  if (spans.some((span) => /\\[`'"]/.test(span.value))) return output3;
   const insertions = /* @__PURE__ */ new Map();
   const removals = /* @__PURE__ */ new Map();
   for (const span of spans) {
@@ -33781,28 +33803,28 @@ function rewriteSuggestions(output2, tool, truncated = false) {
       if (!quote2 && /^(?:artium-axi |npx -y @knowttl\/)?\S+-axi(?:\s|$)/.test(command)) commandRanges.push([match.index, match.index + match[0].length]);
       const wrapped = command.startsWith(`artium-axi ${tool}`);
       if (!executable.test(quote2 ? command.split(quote2)[0] : command)) continue;
-      if (quote2 && !command.includes(quote2)) return output2;
+      if (quote2 && !command.includes(quote2)) return output3;
       const start = match.index + match[0].length - command.length;
       commandRanges.push([match.index, quote2 ? start + command.indexOf(quote2) + 1 : match.index + match[0].length]);
       commandEdit2(start, quote2 ? start + command.indexOf(quote2) : start + command.length, wrapped);
     }
     for (const match of span.value.matchAll(/(?<![^\s(])([`'"])([^\n]*?)(\1|(?=\n|$))/g)) {
       if (commandRanges.some(([start, end]) => match.index >= start && match.index < end)) continue;
-      if (!/^(?:artium-axi |npx -y @knowttl\/)?[^\s`'"]+-axi(?:\s|$)/.test(match[2])) return output2;
+      if (!/^(?:artium-axi |npx -y @knowttl\/)?[^\s`'"]+-axi(?:\s|$)/.test(match[2])) return output3;
       const preceding = span.value.slice(0, match.index);
       if (/(?:^|\n)[ \t]*Valid flags for $/.test(preceding) && match[1] === "`" && match[3] === "`") continue;
-      if (!/(?:^|\n|\S[`'"])[ \t]*(?:(?:Run|Use|run|use|Verify with|If you're unsure, run|Check current state before trying again:|or(?:, if you're unsure, run)?)[ \t]+)?$/.test(preceding)) return output2;
+      if (!/(?:^|\n|\S[`'"])[ \t]*(?:(?:Run|Use|run|use|Verify with|If you're unsure, run|Check current state before trying again:|or(?:, if you're unsure, run)?)[ \t]+)?$/.test(preceding)) return output3;
       const wrapped = match[2].startsWith(`artium-axi ${tool}`);
       if (executable.test(match[2])) {
-        if (!match[3]) return output2;
+        if (!match[3]) return output3;
         commandEdit2(match.index + 1, match.index + 1 + match[2].length, wrapped);
       }
     }
   }
   for (const offset of [.../* @__PURE__ */ new Set([...insertions.keys(), ...removals.keys()])].sort((a, b) => b - a)) {
-    output2 = output2.slice(0, offset) + (insertions.get(offset) ?? "") + output2.slice(removals.get(offset) ?? offset);
+    output3 = output3.slice(0, offset) + (insertions.get(offset) ?? "") + output3.slice(removals.get(offset) ?? offset);
   }
-  return output2;
+  return output3;
 }
 function managedFlagRanges(command, tool) {
   const tokens = [...command.matchAll(/(?:[^\s;'"`]+|'[^']*'|"(?:\\.|[^"\\])*")+|;/g)];
@@ -33848,10 +33870,10 @@ function hostedHelp(help, tool, flags, commands2) {
     (match, separator) => separator ? `; artium-axi ${tool}` : match
   )).replace(new RegExp("`(?:npx -y @knowttl/)?" + tool + "(?=\\s|`)([^\\r\\n`]*`)", "g"), "`artium-axi " + tool + "$1").replace(new RegExp(`^([ 	]*cat [^\\r\\n|]+ \\| )(?:npx -y @knowttl/)?${tool}(?=\\s|$)`, "gm"), `$1artium-axi ${tool}`).replace(new RegExp(`\\buse ${tool} entry search\\b`, "g"), `use artium-axi ${tool} entry search`);
 }
-function jsonHelp(output2) {
-  const parsed = JSON.parse(output2);
+function jsonHelp(output3) {
+  const parsed = JSON.parse(output3);
   if (typeof parsed.help !== "string" && !(Array.isArray(parsed.help) && parsed.help.every((item) => typeof item === "string"))) return { spans: [], document: parsed };
-  const tokens = [...output2.matchAll(/"(?:\\[\s\S]|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}\[\]:,]/g)];
+  const tokens = [...output3.matchAll(/"(?:\\[\s\S]|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}\[\]:,]/g)];
   const spans = [];
   let index = 0;
   let helpFields = 0;
@@ -33879,8 +33901,8 @@ function jsonHelp(output2) {
   value(false, true);
   return { spans: helpFields === 1 ? spans : [], document: parsed };
 }
-function toonHelp(output2) {
-  const lines = [...output2.matchAll(/[^\r\n]*(?:\r\n|\n|$)/g)].filter((line) => line[0]);
+function toonHelp(output3) {
+  const lines = [...output3.matchAll(/[^\r\n]*(?:\r\n|\n|$)/g)].filter((line) => line[0]);
   const spans = [];
   const validation = lines.map((line) => line[0].replace(/\r?\n$/, ""));
   let helpFields = 0;
@@ -34059,15 +34081,15 @@ function claudeSettings(path, executable) {
   if (!Array.isArray(sessions) || sessions.some((entry) => !object2(entry) || !Array.isArray(entry.hooks) || entry.hooks.some((hook) => !object2(hook)))) {
     throw new ArtiumError("INVALID_INPUT", "Claude SessionStart hooks have an unsupported shape; no installation was written.");
   }
-  const managed = { type: "command", command: process.execPath, args: [executable, "tools"], statusMessage: hookName };
+  const managed2 = { type: "command", command: process.execPath, args: [executable, "tools"], statusMessage: hookName };
   let found = false;
   const merged = sessions.map((entry) => ({ ...entry, hooks: entry.hooks.flatMap((hook) => {
     if (hook.statusMessage !== hookName) return [hook];
     if (found) return [];
     found = true;
-    return [managed];
+    return [managed2];
   }) }));
-  if (!found) merged.push({ hooks: [managed] });
+  if (!found) merged.push({ hooks: [managed2] });
   settings.hooks = { ...hooks, SessionStart: merged };
   return JSON.stringify(settings, null, 2) + "\n";
 }
@@ -34194,10 +34216,11 @@ async function toolInput(tool, original) {
 
 // src/cli/device.ts
 import { setTimeout as setTimeout2 } from "node:timers/promises";
-async function ssoLogin(client) {
+async function ssoLogin(client, managed2) {
   const parsed = deviceStartResponseSchema.safeParse(await client.request("/v1/auth/device", "POST", {}));
   if (!parsed.success) throw new ArtiumError("INVALID_RESPONSE");
   const device = parsed.data;
+  managed2?.protect(device.deviceCode);
   if (device.verificationUri !== client.serverUrl + "/device") throw new ArtiumError("INVALID_RESPONSE");
   process.stdout.write(`status: approval-required
 open: ${JSON.stringify(device.verificationUri)}
@@ -34211,13 +34234,16 @@ expires: ${new Date(device.expiresAt).toISOString()}
       if (!response.success || response.data.status === "password-change-required") throw new ArtiumError("INVALID_RESPONSE");
       if (response.data.status === "authenticated") {
         const session = response.data;
-        await client.sessions.locked(async () => {
+        if (managed2) await managed2.emit(client.serverUrl, session);
+        else await client.sessions.locked(async () => {
           client.sessions.write(session);
         });
-        process.stdout.write(`status: authenticated
+        const message = `status: authenticated
 session-ends: ${new Date(session.familyExpiresAt).toISOString()}
 next: artium-axi tools
-`);
+`;
+        if (managed2) managed2.write("stdout", message);
+        else process.stdout.write(message);
         return;
       }
     } catch (error62) {
@@ -34228,10 +34254,190 @@ next: artium-axi tools
   throw new ArtiumError("DEVICE_CODE_EXPIRED");
 }
 
+// src/cli/managed-session.ts
+import { fstatSync, writeSync } from "node:fs";
+import { Socket } from "node:net";
+
+// src/server/runner/scan.ts
+function prefixLengths(bytes) {
+  const lengths = new Uint32Array(bytes.length);
+  let length = 0;
+  for (let index = 1; index < bytes.length; index++) {
+    while (length > 0 && bytes[index] !== bytes[length]) length = lengths[length - 1];
+    if (bytes[index] === bytes[length]) length++;
+    lengths[index] = length;
+  }
+  return lengths;
+}
+var SecretScanner = class {
+  #patterns;
+  #positions;
+  #matched = false;
+  constructor(secrets) {
+    const forms = /* @__PURE__ */ new Set();
+    for (const secret of secrets) {
+      if (secret.length === 0) throw new Error("Secret values must be nonempty");
+      const bytes = Buffer.from(secret, "utf8");
+      forms.add(secret);
+      forms.add(bytes.toString("base64"));
+      forms.add(bytes.toString("base64url"));
+      forms.add(encodeURIComponent(secret));
+      forms.add(JSON.stringify(secret).slice(1, -1));
+    }
+    this.#patterns = [...forms].map((form) => {
+      const bytes = Buffer.from(form, "utf8");
+      return { bytes, prefixes: prefixLengths(bytes) };
+    });
+    this.#positions = {
+      stdout: new Uint32Array(this.#patterns.length),
+      stderr: new Uint32Array(this.#patterns.length)
+    };
+  }
+  scan(stream, chunk) {
+    if (this.#matched) return true;
+    const positions = this.#positions[stream];
+    for (let index = 0; index < this.#patterns.length; index++) {
+      const { bytes, prefixes } = this.#patterns[index];
+      let position = positions[index];
+      for (const byte of chunk) {
+        while (position > 0 && byte !== bytes[position]) position = prefixes[position - 1];
+        if (byte === bytes[position]) position++;
+        if (position === bytes.length) {
+          this.#matched = true;
+          return true;
+        }
+      }
+      positions[index] = position;
+    }
+    return false;
+  }
+};
+
+// src/cli/managed-session.ts
+var sessionSchema = external_exports.strictObject({
+  serverUrl: external_exports.string().url(),
+  accessToken: external_exports.string().min(1),
+  refreshToken: external_exports.string().min(1).optional(),
+  status: external_exports.literal("authenticated").optional(),
+  accessExpiresAt: external_exports.number().int().optional(),
+  familyExpiresAt: external_exports.number().int().optional()
+});
+var ManagedSession = class _ManagedSession {
+  constructor(channel, session) {
+    this.channel = channel;
+    this.session = session;
+    if (session) this.protect(session.accessToken, ...session.refreshToken ? [session.refreshToken] : []);
+  }
+  channel;
+  session;
+  secrets = [];
+  output = { stdout: "", stderr: "" };
+  static async read(signIn = false) {
+    try {
+      for (const fd of signIn ? [4] : [3, 4]) {
+        const stat = fstatSync(fd);
+        if (!stat.isFIFO() && !stat.isSocket()) throw new Error();
+      }
+      writeSync(4, Buffer.alloc(0));
+      let session;
+      if (!signIn) {
+        const input2 = new Socket({ fd: 3, readable: true, writable: false });
+        const chunks = [];
+        let bytes = 0;
+        for await (const chunk of input2) {
+          bytes += chunk.length;
+          if (bytes > 64 * 1024) {
+            input2.destroy();
+            throw new Error();
+          }
+          chunks.push(chunk);
+        }
+        session = sessionSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+      }
+      const channel = new Socket({ fd: 4, readable: false, writable: true });
+      channel.on("error", () => {
+      });
+      return new _ManagedSession(channel, session);
+    } catch {
+      throw new ArtiumError(
+        "INVALID_INPUT",
+        "Managed session input or private descriptors are invalid.",
+        signIn ? "Supply a writable private pipe on fd 4 for the new session." : "Supply session JSON on inherited pipe fd 3 and a writable private pipe on fd 4; close fd 3 after sending JSON."
+      );
+    }
+  }
+  checkServer(serverUrl) {
+    if (this.session && this.session.serverUrl.replace(/\/$/, "") !== serverUrl) throw new ArtiumError("SESSION_SERVER_MISMATCH");
+  }
+  async authenticated(request, refresh) {
+    if (!this.session) throw new ArtiumError("TOKEN_INVALID");
+    try {
+      return await request(this.session.accessToken);
+    } catch (error62) {
+      if (!(error62 instanceof ArtiumError) || error62.code !== "TOKEN_EXPIRED" || !this.session.refreshToken) throw error62;
+    }
+    const parsed = loginResponseSchema.safeParse(await refresh(this.session.refreshToken));
+    if (!parsed.success || parsed.data.status !== "authenticated" || !parsed.data.accessToken || !parsed.data.refreshToken) {
+      throw new ArtiumError("INVALID_RESPONSE");
+    }
+    await this.emit(this.session.serverUrl, parsed.data);
+    this.session = { serverUrl: this.session.serverUrl, ...parsed.data };
+    return request(this.session.accessToken);
+  }
+  protect(...secrets) {
+    this.secrets.push(...secrets.filter((secret) => secret.length > 0));
+  }
+  async emit(serverUrl, session) {
+    if (session.status === "authenticated") this.protect(session.accessToken, session.refreshToken);
+    else this.protect(session.passwordChangeToken);
+    try {
+      await new Promise((resolve3, reject) => {
+        this.channel.write(`${JSON.stringify({ serverUrl, ...session })}
+`, (error62) => error62 ? reject(error62) : resolve3());
+      });
+    } catch {
+      throw new ArtiumError(
+        "INVALID_INPUT",
+        "Managed session could not be returned.",
+        "Recover the session through the caller; do not reuse a consumed refresh token."
+      );
+    }
+  }
+  write(stream, text2) {
+    this.output[stream] += text2;
+  }
+  flush() {
+    this.channel.destroy();
+    const scanner = new SecretScanner(this.secrets);
+    if (scanner.scan("stdout", Buffer.from(this.output.stdout)) || scanner.scan("stderr", Buffer.from(this.output.stderr))) {
+      throw new ArtiumError("SECRET_IN_OUTPUT");
+    }
+    process.stdout.write(this.output.stdout);
+    process.stderr.write(this.output.stderr);
+  }
+};
+
 // src/cli/main.ts
+var managed;
+function output2(stream, text2) {
+  if (managed) managed.write(stream, text2);
+  else process[stream].write(text2);
+}
 async function main(args) {
+  const managedMode = args[0] === "--managed-session";
+  if (managedMode) {
+    args = args.slice(1);
+    if (["passwd", "logout", "setup"].includes(args[0])) {
+      throw new ArtiumError(
+        "INVALID_INPUT",
+        "This command is unavailable in managed session mode.",
+        "The caller manages session persistence, password changes and revocation."
+      );
+    }
+    managed = await ManagedSession.read(args[0] === "login");
+  }
   if (args.length === 1 && args[0] === "--version") {
-    process.stdout.write(`${cliVersion}
+    output2("stdout", `${cliVersion}
 `);
     return;
   }
@@ -34241,22 +34447,30 @@ async function main(args) {
   const help = helpCommand(prefixHelp ? [...args, "--help"] : args, prefixHelp);
   if (prefixHelp && !help) throw new ArtiumError("INVALID_INPUT", void 0, "Use artium-axi --help for commands.");
   if (help) {
-    process.stdout.write(commandHelp(help));
+    output2("stdout", commandHelp(help));
     return;
   }
   if (command === "setup") {
-    process.stdout.write(await setup(args.slice(1)));
+    output2("stdout", await setup(args.slice(1)));
     return;
   }
   if (command === "doctor") {
     if (args.length !== 1) throw new ArtiumError("INVALID_INPUT", void 0, "Use artium-axi doctor.");
-    await doctor();
+    if (managed) await doctor(() => new Client(process.env, managed), (text2) => output2("stdout", text2));
+    else await doctor();
     return;
   }
   if (command === "login" || command === "passwd") {
     const remaining = args.slice(1);
+    if (managed && process.env.ARTIUM_AXI_PASSWORD !== void 0) {
+      throw new ArtiumError(
+        "INVALID_INPUT",
+        "Password environment values are refused in managed mode.",
+        "Unset ARTIUM_AXI_PASSWORD; use --password-stdin for local sign-in or --sso."
+      );
+    }
     if (command === "login" && remaining.length === 1 && remaining[0] === "--sso") {
-      await ssoLogin(new Client());
+      await ssoLogin(new Client(process.env, managed), managed);
       return;
     }
     let stdin = false;
@@ -34275,24 +34489,34 @@ async function main(args) {
         command === "login" ? "Use artium-axi login --sso or artium-axi login --username <username> --password-stdin." : "Use artium-axi passwd --password-stdin."
       );
     }
-    const client2 = new Client();
+    const client2 = new Client(process.env, managed);
     if (command === "login") {
+      if (managed && !stdin) {
+        throw new ArtiumError(
+          "INVALID_INPUT",
+          "Managed login requires protected password input.",
+          "Use --password-stdin with inherited stdin; unset ARTIUM_AXI_PASSWORD. Password arguments and environment values are refused."
+        );
+      }
       const password = await readPassword(stdin, "ARTIUM_AXI_PASSWORD");
-      const session = await client2.sessions.locked(async () => {
+      managed?.protect(password);
+      const signIn = async () => {
         const parsed = loginResponseSchema.safeParse(await client2.request("/v1/auth/login", "POST", { username, password }));
         if (!parsed.success) throw new ArtiumError("INVALID_RESPONSE");
-        client2.sessions.write(parsed.data);
+        if (managed) await managed.emit(client2.serverUrl, parsed.data);
+        else client2.sessions.write(parsed.data);
         return parsed.data;
-      });
+      };
+      const session = await (managed ? signIn() : client2.sessions.locked(signIn));
       if (session.status === "password-change-required") throw new ArtiumError("PASSWORD_CHANGE_REQUIRED");
-      process.stdout.write("status: authenticated\nnext: artium-axi tools\n");
+      output2("stdout", "status: authenticated\nnext: artium-axi tools\n");
     } else {
       await client2.changePassword(async (session) => {
         const newPassword = await readPassword(stdin);
         const currentPassword = session.status === "authenticated" ? await readPassword(false, "ARTIUM_AXI_CURRENT_PASSWORD") : void 0;
         return { newPassword, ...currentPassword === void 0 ? {} : { currentPassword } };
       });
-      process.stdout.write("status: password-changed\nnext: artium-axi login --username <username> --password-stdin\n");
+      output2("stdout", "status: password-changed\nnext: artium-axi login --username <username> --password-stdin\n");
     }
     return;
   }
@@ -34317,10 +34541,10 @@ async function main(args) {
         return false;
       }
     });
-    process.stdout.write(`status: logged-out
+    output2("stdout", `status: logged-out
 remoteRevocation: ${verified ? "verified" : "unverified"}
 `);
-    if (!verified) process.stdout.write("next: Remote revocation is unverified. The local tokens were removed.\n");
+    if (!verified) output2("stdout", "next: Remote revocation is unverified. The local tokens were removed.\n");
     return;
   }
   const home = args.length === 0;
@@ -34331,25 +34555,25 @@ remoteRevocation: ${verified ? "verified" : "unverified"}
     throw new ArtiumError("INVALID_INPUT", "Unknown command, argument or flag.", "Use artium-axi --help for commands or artium-axi <command> --help for valid flags.");
   }
   const input2 = home || listing || whoami ? void 0 : await toolInput(command, args.slice(1));
-  const client = new Client();
-  const homeSession = home ? client.sessions.read() : void 0;
-  if (home && !homeSession) throw new ArtiumError("TOKEN_INVALID", void 0, "Run artium-axi login --username <username> --password-stdin.");
+  const client = new Client(process.env, managed);
+  const homeSession = home && !managed ? client.sessions.read() : void 0;
+  if (home && !managed && !homeSession) throw new ArtiumError("TOKEN_INVALID", void 0, "Run artium-axi login --username <username> --password-stdin.");
   const result = await client.authenticated(home || whoami ? "/v1/me" : `/v1/tools${listing ? "" : `/${command}/run`}`, home || listing || whoami ? "GET" : "POST", input2, homeSession);
   if (home || whoami) {
     const parsed = meResponseSchema.safeParse(result);
     if (!parsed.success) throw new ArtiumError("INVALID_RESPONSE");
-    let output2 = identityView(parsed.data, client.serverUrl);
+    let view = identityView(parsed.data, client.serverUrl);
     if (home) {
       const tools = toolsResponseSchema.safeParse(await client.authenticated("/v1/tools", "GET", void 0, homeSession));
       if (!tools.success) throw new ArtiumError("INVALID_RESPONSE");
       const executable = resolve2(process.argv[1]);
       const local = relative(homedir3(), executable);
       const bin = local && !isAbsolute(local) && !local.startsWith(`..${sep}`) && local !== ".." ? `~${sep}${local}` : executable;
-      output2 = `bin: ${JSON.stringify(bin)}
+      view = `bin: ${JSON.stringify(bin)}
 description: Run managed upstream tools through one local sign-in.
-${output2}${toolsView(tools.data.tools)}`;
+${view}${toolsView(tools.data.tools)}`;
     }
-    process.stdout.write(output2);
+    output2("stdout", view);
   } else if (listing) {
     const parsed = toolsResponseSchema.safeParse(result);
     if (!parsed.success) throw new ArtiumError("INVALID_RESPONSE");
@@ -34357,23 +34581,30 @@ ${output2}${toolsView(tools.data.tools)}`;
     if (detail) {
       const tool = tools.find((tool2) => tool2.name === args[2]);
       if (!tool) throw new ArtiumError("TOOL_NOT_GRANTED", "The tool is not available to your account.", "Ask an administrator to check your role assignments and enabled tools.");
-      process.stdout.write(toolView(tool));
-    } else process.stdout.write(toolsView(tools));
+      output2("stdout", toolView(tool));
+    } else output2("stdout", toolsView(tools));
   } else {
     const parsed = runSuccessSchema.safeParse(result);
     if (!parsed.success || parsed.data.source !== command) throw new ArtiumError("INVALID_RESPONSE");
     const { stdout, stderr, exitCode, truncated } = parsed.data;
-    if (truncated.stdout || truncated.stderr) process.stderr.write(`artium-axi: output truncated (${["stdout", "stderr"].filter((stream) => truncated[stream]).join(", ")}).
+    if (truncated.stdout || truncated.stderr) output2("stderr", `artium-axi: output truncated (${["stdout", "stderr"].filter((stream) => truncated[stream]).join(", ")}).
 `);
-    process.stdout.write(rewriteSuggestions(stdout, command, truncated.stdout));
-    process.stderr.write(rewriteSuggestions(stderr, command, truncated.stderr));
+    output2("stdout", rewriteSuggestions(stdout, command, truncated.stdout));
+    output2("stderr", rewriteSuggestions(stderr, command, truncated.stderr));
     process.exitCode = exitCode;
   }
 }
 function printError(response) {
-  process.stdout.write(`error:
+  output2("stdout", `error:
 ${Object.entries(response.error).map(([key, value]) => `  ${key}: ${JSON.stringify(value)}`).join("\n")}
 `);
   process.exitCode = errors[response.error.code].exitCode;
 }
-main(process.argv.slice(2)).catch((error62) => printError(errorResponse(error62 instanceof ArtiumError ? error62 : new ArtiumError("INTERNAL_ERROR"), randomUUID3())));
+main(process.argv.slice(2)).catch((error62) => printError(errorResponse(error62 instanceof ArtiumError ? error62 : new ArtiumError("INTERNAL_ERROR"), randomUUID3()))).then(() => {
+  try {
+    managed?.flush();
+  } catch {
+    managed = void 0;
+    printError(errorResponse(new ArtiumError("SECRET_IN_OUTPUT"), randomUUID3()));
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/artium-axi",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Client CLI and embedded skill for the Artium managed tools server.",
   "license": "MIT",
   "type": "module",