@oxygen-agent/cli 1.46.0 → 1.64.5

package/README.md

@@ -7,6 +7,12 @@ OXYGEN is the CLI/API-first GTM engineering workspace for early-stage B2B SaaS t
 - Node.js >=22.22.0
 - npm >=10.9.0
 
+Supported OSes:
+
+- macOS: credentials are stored in Keychain.
+- Windows: credentials are stored in Windows Credential Manager.
+- Linux: credentials are stored in ~/.config/oxygen/credentials.json with user-only file permissions.
+
 ## Install
 
 ```sh
@@ -14,12 +20,18 @@ npm install -g @oxygen-agent/cli
 oxygen login
 ```
 
+Copy both lines: the login command runs after npm has installed the `oxygen` binary.
+
+On Windows, run the same commands from PowerShell, Windows Terminal, or Command Prompt after installing Node.js with npm added to PATH.
+
 ## Update
 
 ```sh
 oxygen update
 ```
 
+`oxygen update` runs `npm install -g @oxygen-agent/cli@latest`, preserves npm prefixes on macOS, Linux, and Windows, and runs npm through `cmd.exe` on Windows.
+
 For product documentation and support, visit https://oxygen-agent.com.
 
-Version: 1.46.0
+Version: 1.64.5

package/dist/credentials.d.ts

@@ -1,6 +1,19 @@
+export type StoredProfileIdentity = {
+    organization: {
+        id: string;
+        slug: string | null;
+        name: string;
+    };
+    user: {
+        id: string;
+        email: string | null;
+    };
+    capturedAt: string;
+};
 export type StoredCredentials = {
     token: string;
     apiUrl: string;
+    identity?: StoredProfileIdentity;
 };
 export type CredentialProfile = StoredCredentials & {
     name: string;
@@ -23,5 +36,17 @@ export declare function clearCredentials(env?: NodeJS.ProcessEnv, options?: {
     remainingProfiles: number;
 }>;
 export declare function listCredentialProfiles(env?: NodeJS.ProcessEnv): Promise<CredentialProfilesState>;
+export type ProfileResolution = {
+    name: string;
+    source: "env" | "file" | "default";
+    credentials: StoredCredentials | null;
+    exists: boolean;
+};
+export declare function resolveActiveProfile(env?: NodeJS.ProcessEnv): Promise<ProfileResolution>;
+export declare function findProfileNameByOrganizationId(organizationId: string, env?: NodeJS.ProcessEnv): Promise<string | null>;
+export declare function pickProfileNameForIdentity(organizationId: string, candidateSeed: string, env?: NodeJS.ProcessEnv): Promise<{
+    name: string;
+    renamed: boolean;
+}>;
 export declare function switchCredentialProfile(profile: string, env?: NodeJS.ProcessEnv): Promise<CredentialProfile>;
 export declare function normalizeApiUrl(value: string): string;

package/dist/credentials.js

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, chmodSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -9,6 +9,7 @@ const SERVICE_NAME = "oxygen-cli";
 const ACCOUNT_NAME = "default";
 const DEFAULT_API_URL = "https://oxygen-agent.com";
 const DEFAULT_PROFILE_NAME = "default";
+const WINDOWS_CREDENTIAL_PAYLOAD_ENV = "OXYGEN_CLI_WINDOWS_CREDENTIAL_PAYLOAD";
 export function defaultApiUrl(env = process.env) {
     return normalizeApiUrl(env.OXYGEN_API_URL ?? DEFAULT_API_URL);
 }
@@ -42,9 +43,17 @@ export async function saveCredentials(credentials, env = process.env, options =
         token: credentials.token,
         apiUrl: normalizeApiUrl(credentials.apiUrl),
     };
+    if (credentials.identity)
+        normalized.identity = credentials.identity;
     const existing = await readSystemCredentialDocument(env);
     const profile = normalizeProfileName(options.profile ?? readEnvProfile(env) ?? existing?.activeProfile ?? DEFAULT_PROFILE_NAME);
     const profiles = existing ? readProfiles(existing) : {};
+    if (!normalized.identity) {
+        const prior = profiles[profile];
+        if (prior?.identity && prior.token === normalized.token) {
+            normalized.identity = prior.identity;
+        }
+    }
     profiles[profile] = normalized;
     const activeProfile = options.activate === false
         ? readProfileName(existing?.activeProfile) ?? profile
@@ -68,6 +77,7 @@ export async function clearCredentials(env = process.env, options = {}) {
             exitCode: 1,
         });
     }
+    // skipcq: JS-0320
     delete profiles[profile];
     const names = Object.keys(profiles).sort((a, b) => a.localeCompare(b));
     if (names.length === 0) {
@@ -114,6 +124,50 @@ export async function listCredentialProfiles(env = process.env) {
         }),
     };
 }
+export async function resolveActiveProfile(env = process.env) {
+    const envProfile = readEnvProfile(env);
+    const document = await readSystemCredentialDocument(env);
+    const profiles = document ? readProfiles(document) : {};
+    const fileActive = readProfileName(document?.activeProfile);
+    const candidate = envProfile ?? fileActive ?? DEFAULT_PROFILE_NAME;
+    const credentials = profiles[candidate] ?? null;
+    const source = envProfile
+        ? "env"
+        : fileActive
+            ? "file"
+            : "default";
+    return { name: candidate, source, credentials, exists: Boolean(credentials) };
+}
+export async function findProfileNameByOrganizationId(organizationId, env = process.env) {
+    const document = await readSystemCredentialDocument(env);
+    if (!document)
+        return null;
+    const profiles = readProfiles(document);
+    for (const [name, credentials] of Object.entries(profiles)) {
+        if (credentials.identity?.organization.id === organizationId)
+            return name;
+    }
+    return null;
+}
+export async function pickProfileNameForIdentity(organizationId, candidateSeed, env = process.env) {
+    const document = await readSystemCredentialDocument(env);
+    const profiles = document ? readProfiles(document) : {};
+    const existingForOrg = Object.entries(profiles).find(([, credentials]) => credentials.identity?.organization.id === organizationId);
+    if (existingForOrg)
+        return { name: existingForOrg[0], renamed: false };
+    const base = normalizeProfileName(candidateSeed);
+    if (!profiles[base])
+        return { name: base, renamed: false };
+    for (let suffix = 2; suffix < 1000; suffix++) {
+        const next = `${base}-${suffix}`;
+        if (!profiles[next])
+            return { name: next, renamed: true };
+    }
+    throw new OxygenError("profile_collision", "Unable to derive a unique CLI profile name.", {
+        details: { base },
+        exitCode: 1,
+    });
+}
 export async function switchCredentialProfile(profile, env = process.env) {
     const document = await readSystemCredentialDocument(env);
     if (!document) {
@@ -186,19 +240,19 @@ async function readSystemCredentialDocument(env) {
 async function readSystemCredentialPayload(env) {
     const store = credentialStore(env);
     if (store === "keychain")
-        return readMacOSKeychainPayload();
+        return readMacOSKeychainPayload(env);
     if (store === "credential-manager")
-        return readWindowsCredentialManagerPayload();
+        return readWindowsCredentialManagerPayload(env);
     return readFileCredentialPayload(env);
 }
 async function writeSystemCredentialPayload(payload, env) {
     const store = credentialStore(env);
     if (store === "keychain") {
-        await writeMacOSKeychainPayload(payload);
+        await writeMacOSKeychainPayload(payload, env);
         return;
     }
     if (store === "credential-manager") {
-        await writeWindowsCredentialManagerPayload(payload);
+        await writeWindowsCredentialManagerPayload(payload, env);
         return;
     }
     writeFileCredentialPayload(payload, env);
@@ -206,11 +260,11 @@ async function writeSystemCredentialPayload(payload, env) {
 async function deleteSystemCredentialPayload(env) {
     const store = credentialStore(env);
     if (store === "keychain") {
-        await deleteMacOSKeychain();
+        await deleteMacOSKeychain(env);
         return;
     }
     if (store === "credential-manager") {
-        await deleteWindowsCredentialManager();
+        await deleteWindowsCredentialManager(env);
         return;
     }
     deleteFileCredentials(env);
@@ -229,6 +283,8 @@ async function writeCredentialDocument(input, env) {
         activeProfile: input.activeProfile,
         profiles: input.profiles,
     };
+    if (activeCredentials.identity)
+        document.identity = activeCredentials.identity;
     await writeSystemCredentialPayload(serializeCredentialDocument(document), env);
 }
 function credentialStore(env) {
@@ -271,63 +327,97 @@ function deleteFileCredentials(env) {
     const path = credentialsPath(env);
     rmSync(path, { force: true });
 }
-async function readMacOSKeychainPayload() {
+async function readMacOSKeychainPayload(env) {
     try {
-        const { stdout } = await execFileAsync("security", [
+        const { stdout } = await execFileAsync(macOSSecurityCommand(env), [
             "find-generic-password",
             "-a",
             ACCOUNT_NAME,
             "-s",
             SERVICE_NAME,
             "-w",
-        ]);
+        ], { env });
         return stdout;
     }
     catch {
         return null;
     }
 }
-async function writeMacOSKeychainPayload(payload) {
-    await execFileAsync("security", [
-        "add-generic-password",
-        "-a",
-        ACCOUNT_NAME,
-        "-s",
-        SERVICE_NAME,
-        "-w",
-        payload,
-        "-U",
-    ]);
+// `security -i` reads commands with a line buffer that traditionally caps at
+// 4096 bytes. Beyond that, the input is silently truncated, which would
+// corrupt the stored credential and break re-auth. Reject early with a clear
+// error so a user with too many profiles gets actionable feedback instead of
+// a partial-write that only surfaces on the next CLI invocation.
+const MACOS_SECURITY_LINE_LIMIT_BYTES = 4096;
+async function writeMacOSKeychainPayload(payload, env) {
+    // `security add-generic-password -w PAYLOAD` would put the token in argv
+    // (visible to any same-UID `ps`). Use `security -i` instead: the subcommand
+    // is written on stdin, so the only argv `ps` ever sees is `security -i`.
+    const command = macOSSecurityCommand(env);
+    const escaped = payload.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+    const line = `add-generic-password -a "${ACCOUNT_NAME}" -s "${SERVICE_NAME}" -w "${escaped}" -U\n`;
+    const lineBytes = Buffer.byteLength(line, "utf8");
+    if (lineBytes >= MACOS_SECURITY_LINE_LIMIT_BYTES) {
+        throw credentialStoreError("write", "macOS Keychain", {
+            code: "payload_too_large",
+            stderr: `Credential document is ${lineBytes} bytes; \`security -i\` truncates lines at ${MACOS_SECURITY_LINE_LIMIT_BYTES} bytes. Reduce stored profiles (oxygen logout <profile>) and retry.`,
+        });
+    }
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, ["-i"], { env, stdio: ["pipe", "pipe", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.once("error", (error) => {
+            reject(credentialStoreError("write", "macOS Keychain", error));
+        });
+        child.once("close", (code, signal) => {
+            const trimmedStderr = stderr.trim();
+            if (code === 0 && !trimmedStderr) {
+                resolve();
+                return;
+            }
+            reject(credentialStoreError("write", "macOS Keychain", { code, signal, stderr: trimmedStderr }));
+        });
+        child.stdin.end(line);
+    });
 }
-async function deleteMacOSKeychain() {
-    await execFileAsync("security", [
+async function deleteMacOSKeychain(env) {
+    await execFileAsync(macOSSecurityCommand(env), [
         "delete-generic-password",
         "-a",
         ACCOUNT_NAME,
         "-s",
         SERVICE_NAME,
-    ]).catch(() => undefined);
+    ], { env }).catch(() => undefined);
 }
-async function readWindowsCredentialManagerPayload() {
+async function readWindowsCredentialManagerPayload(env) {
     try {
         const { stdout } = await runPowerShell(`${windowsCredentialManagerScript()}
 $ptr = [IntPtr]::Zero
-if (-not [OxygenCredMan]::CredRead("${SERVICE_NAME}", 1, 0, [ref]$ptr)) { exit 2 }
-$cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][OxygenCredMan+CREDENTIAL])
-$secret = [Runtime.InteropServices.Marshal]::PtrToStringUni($cred.CredentialBlob, [int]($cred.CredentialBlobSize / 2))
-[OxygenCredMan]::CredFree($ptr)
-[Console]::Out.Write($secret)
-`);
+try {
+  if (-not [OxygenCredMan]::CredRead("${SERVICE_NAME}", 1, 0, [ref]$ptr)) { exit 2 }
+  $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][OxygenCredMan+CREDENTIAL])
+  $secret = [Runtime.InteropServices.Marshal]::PtrToStringUni($cred.CredentialBlob, [int]($cred.CredentialBlobSize / 2))
+  [Console]::Out.Write($secret)
+} finally {
+  if ($ptr -ne [IntPtr]::Zero) { [OxygenCredMan]::CredFree($ptr) }
+}
+`, env);
         return stdout;
     }
     catch {
         return null;
     }
 }
-async function writeWindowsCredentialManagerPayload(value) {
+async function writeWindowsCredentialManagerPayload(value, env) {
     const payload = Buffer.from(value, "utf16le").toString("base64");
-    await runPowerShell(`${windowsCredentialManagerScript()}
-$secret = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($args[0]))
+    try {
+        await runPowerShell(`${windowsCredentialManagerScript()}
+$payload = $env:${WINDOWS_CREDENTIAL_PAYLOAD_ENV}
+if ([string]::IsNullOrWhiteSpace($payload)) { exit 1 }
+$secret = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($payload))
 $bytes = [Text.Encoding]::Unicode.GetBytes($secret)
 $blob = [Runtime.InteropServices.Marshal]::StringToCoTaskMemUni($secret)
 try {
@@ -342,23 +432,58 @@ try {
 } finally {
   [Runtime.InteropServices.Marshal]::FreeCoTaskMem($blob)
 }
-`, [payload]);
+`, {
+            ...env,
+            [WINDOWS_CREDENTIAL_PAYLOAD_ENV]: payload,
+        });
+    }
+    catch (error) {
+        throw credentialStoreError("write", "Windows Credential Manager", error);
+    }
 }
-async function deleteWindowsCredentialManager() {
+async function deleteWindowsCredentialManager(env) {
     await runPowerShell(`${windowsCredentialManagerScript()}
 [void][OxygenCredMan]::CredDelete("${SERVICE_NAME}", 1, 0)
-`).catch(() => undefined);
+`, env).catch(() => undefined);
 }
-async function runPowerShell(script, args = []) {
-    return execFileAsync("powershell.exe", [
+function runPowerShell(script, env) {
+    const encodedCommand = Buffer.from(script, "utf16le").toString("base64");
+    return execFileAsync(windowsPowerShellCommand(env), [
         "-NoProfile",
         "-NonInteractive",
         "-ExecutionPolicy",
         "Bypass",
-        "-Command",
-        script,
-        ...args,
-    ]);
+        "-EncodedCommand",
+        encodedCommand,
+    ], { env });
+}
+function credentialStoreError(operation, store, error) {
+    const child = error;
+    const details = {
+        operation,
+        store,
+    };
+    if (typeof child.code === "number") {
+        details.exit_code = child.code;
+    }
+    else if (typeof child.code === "string") {
+        details.reason = child.code;
+    }
+    if (typeof child.signal === "string")
+        details.signal = child.signal;
+    if (typeof child.stderr === "string" && child.stderr.trim()) {
+        details.stderr = sanitizeCredentialErrorText(child.stderr.trim()).slice(0, 4000);
+    }
+    return new OxygenError("credential_store_failed", `Unable to ${operation} Oxygen CLI credentials in ${store}.`, { details, exitCode: 1 });
+}
+function sanitizeCredentialErrorText(value) {
+    return value.replace(/\boxy_live_[A-Za-z0-9_-]+\b/g, "[redacted_token]");
+}
+function macOSSecurityCommand(env) {
+    return env.OXYGEN_SECURITY_COMMAND?.trim() || "security";
+}
+function windowsPowerShellCommand(env) {
+    return env.OXYGEN_POWERSHELL_COMMAND?.trim() || "powershell.exe";
 }
 function windowsCredentialManagerScript() {
     return `
@@ -445,16 +570,60 @@ function parseStoredCredentialsObject(value) {
         return null;
     if (typeof apiUrl !== "string" || !apiUrl.trim())
         return null;
-    return { token: token.trim(), apiUrl: normalizeApiUrl(apiUrl) };
+    const credentials = {
+        token: token.trim(),
+        apiUrl: normalizeApiUrl(apiUrl),
+    };
+    const identity = parseStoredProfileIdentity(value.identity);
+    if (identity)
+        credentials.identity = identity;
+    return credentials;
+}
+function parseStoredProfileIdentity(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const org = record.organization;
+    const user = record.user;
+    if (!org || typeof org !== "object" || Array.isArray(org))
+        return null;
+    if (!user || typeof user !== "object" || Array.isArray(user))
+        return null;
+    const orgRecord = org;
+    const userRecord = user;
+    const orgId = typeof orgRecord.id === "string" ? orgRecord.id.trim() : "";
+    const orgName = typeof orgRecord.name === "string" ? orgRecord.name : "";
+    if (!orgId || !orgName)
+        return null;
+    const orgSlug = typeof orgRecord.slug === "string" && orgRecord.slug.trim()
+        ? orgRecord.slug.trim()
+        : null;
+    const userId = typeof userRecord.id === "string" ? userRecord.id.trim() : "";
+    if (!userId)
+        return null;
+    const userEmail = typeof userRecord.email === "string" && userRecord.email.trim()
+        ? userRecord.email.trim()
+        : null;
+    const capturedAt = typeof record.capturedAt === "string" && record.capturedAt.trim()
+        ? record.capturedAt.trim()
+        : new Date(0).toISOString();
+    return {
+        organization: { id: orgId, slug: orgSlug, name: orgName },
+        user: { id: userId, email: userEmail },
+        capturedAt,
+    };
 }
 function readProfiles(document) {
     const profiles = {};
     const rawProfiles = document.profiles ?? {};
     for (const [name, credentials] of Object.entries(rawProfiles)) {
-        profiles[normalizeProfileName(name)] = {
+        const normalized = {
             token: credentials.token,
             apiUrl: normalizeApiUrl(credentials.apiUrl),
         };
+        if (credentials.identity)
+            normalized.identity = credentials.identity;
+        profiles[normalizeProfileName(name)] = normalized;
     }
     if (Object.keys(profiles).length === 0) {
         const defaultCredentials = parseStoredCredentialsObject(document);