@knowttl/artium-axi 0.0.3 → 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. |
@@ -679,12 +679,12 @@ 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 and fd 4 for private rotation output.
+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.
 
-Send one UTF-8 JSON object of at most 64 KiB to fd 3, then close the input pipe:
+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"}
@@ -693,11 +693,21 @@ Send one UTF-8 JSON object of at most 64 KiB to fd 3, then close the input pipe:
 `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 token acquisition, expiry policy, refresh serialization across processes and secure persistence.
-Managed mode supports the home view, `whoami`, `tools`, `tools show`, `doctor` and tool commands.
-`login`, `passwd`, `logout` and `setup` are refused before any network call; ordinary sign-in and its server-version warning remain unchanged without the flag.
+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.
@@ -707,10 +717,12 @@ After a successful refresh, fd 4 receives one newline-terminated JSON object bef
 {"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 invocation without rotation writes no record.
-Consume fd 4 concurrently with stdout and stderr, and retain rotations regardless of the command's exit status.
-If rotation delivery fails, the CLI refuses to retry the request and returns `INVALID_INPUT` (exit 2); the caller must recover the session rather than reuse the consumed refresh token.
-Managed public output is buffered and scanned against supplied and rotated tokens and their canonical encodings before printing; a match withholds both streams and returns `SECRET_IN_OUTPUT`.
+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.

package/bin/artium-axi.mjs

@@ -20452,7 +20452,7 @@ import { rootCertificates } from "node:tls";
 // package.json
 var package_default = {
   name: "artium-axi",
-  version: "0.0.3",
+  version: "0.0.4",
   private: true,
   license: "MIT",
   type: "module",
@@ -20726,8 +20726,10 @@ 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;
   }
@@ -22894,9 +22896,10 @@ function commandHelp(command) {
   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; authenticated calls only; session JSON on inherited pipe fd 3, rotations as JSON lines on private pipe fd 4; no session file)",
+    "--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 exits: 0 success; 2 invalid JSON/descriptors or refused login/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."
+    "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}
@@ -34213,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)}
@@ -34230,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) {
@@ -34316,50 +34323,54 @@ var sessionSchema = external_exports.strictObject({
   familyExpiresAt: external_exports.number().int().optional()
 });
 var ManagedSession = class _ManagedSession {
-  constructor(session, channel) {
-    this.session = session;
+  constructor(channel, session) {
     this.channel = channel;
-    this.secrets = [session.accessToken, ...session.refreshToken ? [session.refreshToken] : []];
+    this.session = session;
+    if (session) this.protect(session.accessToken, ...session.refreshToken ? [session.refreshToken] : []);
   }
-  session;
   channel;
-  secrets;
+  session;
+  secrets = [];
   output = { stdout: "", stderr: "" };
-  static async read() {
+  static async read(signIn = false) {
     try {
-      for (const fd of [3, 4]) {
+      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));
-      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();
+      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);
         }
-        chunks.push(chunk);
+        session = sessionSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
       }
-      const 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(session, channel);
+      return new _ManagedSession(channel, session);
     } catch {
       throw new ArtiumError(
         "INVALID_INPUT",
         "Managed session input or private descriptors are invalid.",
-        "Supply session JSON on inherited pipe fd 3 and a writable private pipe on fd 4; close fd 3 after sending JSON."
+        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.serverUrl.replace(/\/$/, "") !== serverUrl) throw new ArtiumError("SESSION_SERVER_MISMATCH");
+    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) {
@@ -34369,21 +34380,28 @@ var ManagedSession = class _ManagedSession {
     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 };
-    this.secrets.push(parsed.data.accessToken, parsed.data.refreshToken);
+    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(this.session)}
+        this.channel.write(`${JSON.stringify({ serverUrl, ...session })}
 `, (error62) => error62 ? reject(error62) : resolve3());
       });
     } catch {
       throw new ArtiumError(
         "INVALID_INPUT",
-        "Managed session rotation could not be returned.",
-        "Recover the session through the caller; do not retry using the old refresh token."
+        "Managed session could not be returned.",
+        "Recover the session through the caller; do not reuse a consumed refresh token."
       );
     }
-    return request(this.session.accessToken);
   }
   write(stream, text2) {
     this.output[stream] += text2;
@@ -34409,14 +34427,14 @@ async function main(args) {
   const managedMode = args[0] === "--managed-session";
   if (managedMode) {
     args = args.slice(1);
-    if (["login", "passwd", "logout", "setup"].includes(args[0])) {
+    if (["passwd", "logout", "setup"].includes(args[0])) {
       throw new ArtiumError(
         "INVALID_INPUT",
         "This command is unavailable in managed session mode.",
-        "The caller must acquire and manage tokens; use managed mode for authenticated calls."
+        "The caller manages session persistence, password changes and revocation."
       );
     }
-    managed = await ManagedSession.read();
+    managed = await ManagedSession.read(args[0] === "login");
   }
   if (args.length === 1 && args[0] === "--version") {
     output2("stdout", `${cliVersion}
@@ -34444,8 +34462,15 @@ async function main(args) {
   }
   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;
@@ -34464,15 +34489,25 @@ 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");
       output2("stdout", "status: authenticated\nnext: artium-axi tools\n");
     } else {

package/package.json

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