@knowttl/mg-axi 0.1.4 → 0.1.6

package/dist/profiles.js

@@ -1,104 +1,161 @@
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { AxiError } from "axi-sdk-js";
+import { configPath, toolDirectory } from "./paths.js";
+import { PrivateFiles } from "./private-file.js";
+import { validateSecretRef } from "./secrets.js";
+const names = new WeakMap();
 const guid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const namePattern = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+const namePattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
 const exact = (value, keys) => Object.keys(value).every(key => keys.includes(key));
 function invalid(message) {
-    throw new AxiError(message, "VALIDATION_ERROR", ["mg-axi profile create --help", "Correct the version-1 profile configuration; no automatic migration is performed"]);
+    throw new AxiError(message, "CONFIG_INVALID", ["mg-axi profile create --help", "Correct the version-1 profile configuration; no automatic migration is performed"]);
 }
-const thumbprint = /^[0-9a-f]{40}$/i;
-const envName = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const credentialPath = (value) => typeof value === "string" && !!value.trim();
-const exactlyOne = (values) => values.filter(value => value !== undefined).length === 1;
-const sharedKeys = ["mode", "tenantId", "clientId", "cloud", "enabledPacks", "preview", "sensitiveAreas", "credentialRef", "allowDeviceCode", "writes"];
-const MAX_WRITE_OPERATIONS = 64;
-const MAX_WRITE_OPERATION_LENGTH = 256;
-function validateWrites(value) {
-    if (value === undefined)
-        return undefined;
-    if (!object(value) || !exact(value, ["allowWrites", "operations"]) || typeof value.allowWrites !== "boolean" ||
-        !Array.isArray(value.operations) || value.operations.length === 0 || value.operations.length > MAX_WRITE_OPERATIONS ||
-        value.operations.some(entry => typeof entry !== "string" || !entry.length || entry.length > MAX_WRITE_OPERATION_LENGTH)) {
-        invalid("Invalid write policy; hand-edit a writes object with boolean allowWrites and a nonempty operations array of nonempty operation names");
-    }
-    return Object.freeze({ allowWrites: value.allowWrites, operations: Object.freeze([...value.operations]) });
+export function booleanEnv(name, env = process.env) {
+    const value = env[name]?.toLowerCase();
+    if (value === undefined || value === "0" || value === "false")
+        return false;
+    if (value === "1" || value === "true")
+        return true;
+    return invalid(`Invalid boolean for ${name}; use 1, true, 0 or false`);
 }
-const sharedIdentity = (value) => value.cloud === "commercial" && typeof value.tenantId === "string" && guid.test(value.tenantId) &&
-    typeof value.clientId === "string" && guid.test(value.clientId) && typeof value.preview === "boolean" &&
-    Array.isArray(value.enabledPacks) && value.enabledPacks.every(pack => pack === "entra") && new Set(value.enabledPacks).size === value.enabledPacks.length &&
-    Array.isArray(value.sensitiveAreas) && value.sensitiveAreas.length === 0;
-export function validateDelegatedProfile(value) {
-    if (!object(value) || !exact(value, sharedKeys) || value.mode !== "delegated" || !sharedIdentity(value) || typeof value.allowDeviceCode !== "boolean" ||
-        !object(value.credentialRef) || !exact(value.credentialRef, ["provider", "key"]) || value.credentialRef.provider !== "os-or-session" ||
-        typeof value.credentialRef.key !== "string" || !guid.test(value.credentialRef.key))
-        invalid("Invalid delegated profile; explicit tenant/client IDs and commercial cloud are required, with credentials only by reference");
-    const profile = value;
-    const writes = validateWrites(value.writes);
-    return Object.freeze({ mode: "delegated", tenantId: profile.tenantId, clientId: profile.clientId, cloud: "commercial", preview: profile.preview,
-        allowDeviceCode: profile.allowDeviceCode, enabledPacks: Object.freeze([...profile.enabledPacks]), sensitiveAreas: Object.freeze([]),
-        credentialRef: Object.freeze({ provider: "os-or-session", key: profile.credentialRef.key }), ...(writes === undefined ? {} : { writes }) });
+// Names belong to the selected configuration, never to its serialized profile schema.
+export function profileName(profile) { return names.get(profile); }
+function validated(source, profile) {
+    const name = names.get(source);
+    if (name !== undefined)
+        names.set(profile, name);
+    return Object.freeze(profile);
 }
-export function validateApplicationProfile(value) {
-    if (!object(value) || !exact(value, sharedKeys) || value.mode !== "application" || !sharedIdentity(value) || value.allowDeviceCode !== false ||
-        !object(value.credentialRef))
-        invalid("Invalid application profile; explicit tenant/client IDs and commercial cloud are required, with credentials only by reference");
-    const profile = value;
-    const ref = profile.credentialRef;
-    const writes = validateWrites(value.writes);
-    const writeFields = writes === undefined ? {} : { writes };
-    if (ref.provider === "certificate" && exact(ref, ["provider", "key", "thumbprint", "keyFile", "keyEnv"]) && typeof ref.key === "string" && guid.test(ref.key) &&
-        typeof ref.thumbprint === "string" && thumbprint.test(ref.thumbprint) && ref.keyFile === undefined && ref.keyEnv === undefined) {
-        return Object.freeze({ mode: "application", tenantId: profile.tenantId, clientId: profile.clientId, cloud: "commercial",
-            preview: profile.preview, allowDeviceCode: false, enabledPacks: Object.freeze([...profile.enabledPacks]), sensitiveAreas: Object.freeze([]),
-            credentialRef: Object.freeze({ provider: "certificate", key: ref.key, thumbprint: ref.thumbprint.toLowerCase() }), ...writeFields });
+function shared(value) {
+    if (typeof value.tenantId !== "string" || !guid.test(value.tenantId) || typeof value.clientId !== "string" || !guid.test(value.clientId))
+        invalid("Explicit tenant and client UUIDs are required");
+    if (value.cloud !== undefined && value.cloud !== "commercial")
+        invalid("Only commercial cloud is supported");
+    const packs = value.enabledPacks === undefined ? ["entra"] : value.enabledPacks;
+    const sensitive = value.sensitiveAreas === undefined ? [] : value.sensitiveAreas;
+    const preview = value.preview === undefined ? false : value.preview;
+    if (!Array.isArray(packs) || packs.some(pack => pack !== "entra") || new Set(packs).size !== packs.length ||
+        !Array.isArray(sensitive) || sensitive.length || typeof preview !== "boolean")
+        invalid("Invalid profile policy");
+    let writes;
+    if (value.writes !== undefined) {
+        const policy = value.writes;
+        if (!object(policy) || !exact(policy, ["allowWrites", "operations"]) || typeof policy.allowWrites !== "boolean" ||
+            !Array.isArray(policy.operations) || !policy.operations.length || policy.operations.length > 64 ||
+            policy.operations.some(entry => typeof entry !== "string" || !entry.length || entry.length > 256))
+            invalid("Invalid write policy; use boolean allowWrites and a nonempty operations array");
+        writes = Object.freeze({ allowWrites: policy.allowWrites, operations: Object.freeze([...policy.operations]) });
     }
-    if (ref.provider === "certificate" && exact(ref, ["provider", "key", "thumbprint", "keyFile", "keyEnv"]) && typeof ref.key === "string" && guid.test(ref.key) &&
-        typeof ref.thumbprint === "string" && thumbprint.test(ref.thumbprint) && exactlyOne([ref.keyFile, ref.keyEnv]) &&
-        (ref.keyFile === undefined || credentialPath(ref.keyFile)) && (ref.keyEnv === undefined || (typeof ref.keyEnv === "string" && envName.test(ref.keyEnv)))) {
-        const keySource = ref.keyFile === undefined ? { keyEnv: ref.keyEnv } : { keyFile: ref.keyFile };
-        return Object.freeze({ mode: "application", tenantId: profile.tenantId, clientId: profile.clientId, cloud: "commercial",
-            preview: profile.preview, allowDeviceCode: false, enabledPacks: Object.freeze([...profile.enabledPacks]), sensitiveAreas: Object.freeze([]),
-            credentialRef: Object.freeze({ provider: "certificate", key: ref.key, thumbprint: ref.thumbprint.toLowerCase(), ...keySource }), ...writeFields });
-    }
-    if (ref.provider === "client-secret" && exact(ref, ["provider", "key", "secretEnv", "secretFile"]) && typeof ref.key === "string" && guid.test(ref.key) &&
-        exactlyOne([ref.secretEnv, ref.secretFile]) &&
-        (ref.secretEnv === undefined || (typeof ref.secretEnv === "string" && envName.test(ref.secretEnv))) && (ref.secretFile === undefined || credentialPath(ref.secretFile))) {
-        const secretSource = ref.secretEnv === undefined ? { secretFile: ref.secretFile } : { secretEnv: ref.secretEnv };
-        return Object.freeze({ mode: "application", tenantId: profile.tenantId, clientId: profile.clientId, cloud: "commercial",
-            preview: profile.preview, allowDeviceCode: false, enabledPacks: Object.freeze([...profile.enabledPacks]), sensitiveAreas: Object.freeze([]),
-            credentialRef: Object.freeze({ provider: "client-secret", key: ref.key, ...secretSource }), ...writeFields });
+    return { tenantId: value.tenantId, clientId: value.clientId, cloud: "commercial", enabledPacks: Object.freeze([...packs]),
+        preview: preview, sensitiveAreas: Object.freeze([]), ...(writes === undefined ? {} : { writes }) };
+}
+const sharedKeys = ["mode", "tenantId", "clientId", "cloud", "enabledPacks", "preview", "sensitiveAreas", "allowDeviceCode", "writes"];
+export function validateDelegatedProfile(value, files) {
+    if (!object(value) || value.mode !== "delegated" || !exact(value, [...sharedKeys, "token"]) ||
+        (value.allowDeviceCode !== undefined && typeof value.allowDeviceCode !== "boolean"))
+        invalid("Invalid delegated profile; token must be a SecretRef");
+    return validated(value, { ...shared(value), mode: "delegated", allowDeviceCode: value.allowDeviceCode === true, token: validateSecretRef(value.token, "token", true, files) });
+}
+export function validateApplicationProfile(value, files) {
+    if (!object(value) || value.mode !== "application" || (value.allowDeviceCode !== undefined && value.allowDeviceCode !== false))
+        invalid("Invalid application profile; device code is unavailable");
+    const keys = value.auth === "certificate" ? ["privateKey", "thumbprintSha256"] : value.auth === "client-secret" ? ["clientSecret"] : value.auth === "federated" ? ["token"] : [];
+    if (!keys.length || !exact(value, [...sharedKeys, "auth", ...keys]))
+        invalid("Invalid application profile; auth must be certificate, client-secret or federated with only its credential fields");
+    const base = { ...shared(value), mode: "application", allowDeviceCode: false };
+    if (value.auth === "certificate") {
+        if (typeof value.thumbprintSha256 !== "string" || !/^[0-9a-f]{64}$/i.test(value.thumbprintSha256))
+            invalid("thumbprintSha256 must contain 64 hex digits");
+        return validated(value, { ...base, auth: "certificate", thumbprintSha256: value.thumbprintSha256.toLowerCase(), privateKey: validateSecretRef(value.privateKey, "privateKey", false, files) });
     }
-    if (ref.provider === "federated" && exact(ref, ["provider", "key", "tokenFileEnv"]) && typeof ref.key === "string" && guid.test(ref.key) &&
-        (ref.tokenFileEnv === undefined || (typeof ref.tokenFileEnv === "string" && envName.test(ref.tokenFileEnv)))) {
-        return Object.freeze({ mode: "application", tenantId: profile.tenantId, clientId: profile.clientId, cloud: "commercial",
-            preview: profile.preview, allowDeviceCode: false, enabledPacks: Object.freeze([...profile.enabledPacks]), sensitiveAreas: Object.freeze([]),
-            credentialRef: Object.freeze({ provider: "federated", key: ref.key, ...(ref.tokenFileEnv === undefined ? {} : { tokenFileEnv: ref.tokenFileEnv }) }), ...writeFields });
+    if (value.auth === "client-secret")
+        return validated(value, { ...base, auth: "client-secret", clientSecret: validateSecretRef(value.clientSecret, "clientSecret", false, files) });
+    return validated(value, { ...base, auth: "federated", token: validateSecretRef(value.token, "token", false, files) });
+}
+export function validateProfile(value, files) {
+    return object(value) && value.mode === "application" ? validateApplicationProfile(value, files) : validateDelegatedProfile(value, files);
+}
+function envProfile(env) {
+    const fields = ["MODE", "TENANT_ID", "CLIENT_ID", "AUTH", "CLOUD", "PREVIEW", "ALLOW_DEVICE_CODE", "ENABLED_PACKS", "SENSITIVE_AREAS", "WRITES"];
+    if (!fields.some(field => env[`MG_AXI_${field}`] !== undefined))
+        return undefined;
+    if (!env.MG_AXI_MODE || !env.MG_AXI_TENANT_ID || !env.MG_AXI_CLIENT_ID)
+        invalid("Partial env profile; MG_AXI_MODE, MG_AXI_TENANT_ID and MG_AXI_CLIENT_ID are required");
+    const json = (name) => {
+        if (env[name] === undefined)
+            return undefined;
+        try {
+            return JSON.parse(env[name]);
+        }
+        catch {
+            return invalid(`Invalid JSON field ${name}`);
+        }
+    };
+    const base = { mode: env.MG_AXI_MODE, tenantId: env.MG_AXI_TENANT_ID, clientId: env.MG_AXI_CLIENT_ID, cloud: env.MG_AXI_CLOUD,
+        preview: booleanEnv("MG_AXI_PREVIEW", env), allowDeviceCode: booleanEnv("MG_AXI_ALLOW_DEVICE_CODE", env),
+        enabledPacks: json("MG_AXI_ENABLED_PACKS"), sensitiveAreas: json("MG_AXI_SENSITIVE_AREAS"), writes: json("MG_AXI_WRITES"),
+        ...(env.MG_AXI_AUTH === undefined ? {} : { auth: env.MG_AXI_AUTH }),
+        ...(env.MG_AXI_THUMBPRINT_SHA256 === undefined ? {} : { thumbprintSha256: env.MG_AXI_THUMBPRINT_SHA256 }),
+        ...(env.MG_AXI_CLIENT_SECRET === undefined ? {} : { clientSecret: { env: "MG_AXI_CLIENT_SECRET" } }),
+        ...(env.MG_AXI_PRIVATE_KEY === undefined ? {} : { privateKey: { env: "MG_AXI_PRIVATE_KEY" } }),
+        ...(env.MG_AXI_TOKEN === undefined ? {} : { token: { env: "MG_AXI_TOKEN" } }) };
+    if (base.mode === "delegated") {
+        if (!env.MG_AXI_TOKEN)
+            invalid("Partial env profile; MG_AXI_TOKEN must supply a delegated cache");
+        return validateDelegatedProfile(base);
     }
-    invalid("Invalid application profile; credentialRef must be a certificate, client-secret or federated reference, never inlined key material");
+    const auth = env.MG_AXI_AUTH;
+    const required = auth === "certificate" ? ["PRIVATE_KEY", "THUMBPRINT_SHA256"] : auth === "client-secret" ? ["CLIENT_SECRET"] : auth === "federated" ? ["TOKEN"] : [];
+    if (!required.length || required.some(field => !env[`MG_AXI_${field}`]))
+        invalid("Partial env profile; MG_AXI_AUTH and its required credential fields must be set");
+    return validateApplicationProfile(base);
 }
-export function validateProfile(value) {
-    if (!!value && typeof value === "object" && !Array.isArray(value) && value.mode === "application")
-        return validateApplicationProfile(value);
-    return validateDelegatedProfile(value);
+export function movedError(kind, legacy, target, guidance) {
+    const quote = (path) => `'${path.replace(/'/g, "'\\''")}'`;
+    const move = process.platform === "win32"
+        ? `New-Item -ItemType Directory -Force -Path '${dirname(target).replace(/'/g, "''")}'; Move-Item -LiteralPath '${legacy.replace(/'/g, "''")}' -Destination '${target.replace(/'/g, "''")}'`
+        : `mkdir -p ${quote(dirname(target))} && mv ${quote(legacy)} ${quote(target)}`;
+    throw new AxiError(`${kind} moved from ${legacy} to ${target}`, "CONFIG_MOVED", [move, guidance]);
 }
 export class Profiles {
+    files;
     path;
-    constructor(path = process.env.MG_AXI_CONFIG ?? join(homedir(), ".mg-axi", "config.json")) {
-        this.path = path;
+    constructor(path, files = new PrivateFiles()) {
+        this.files = files;
+        this.path = path?.trim() ? path.trim() : configPath();
+    }
+    moved() {
+        const legacy = join(homedir(), ".mg-axi", "config.json");
+        const target = resolve(this.path) === resolve(legacy) ? join(toolDirectory("config"), "config.json") : this.path;
+        movedError("Configuration", legacy, target, "Update credentialRef to the flattened SecretRef format described in the AXI credential standard");
     }
     load() {
-        let value;
+        const legacy = join(homedir(), ".mg-axi", "config.json");
+        if (resolve(this.path) === resolve(legacy) && existsSync(legacy))
+            this.moved();
+        let text;
         try {
-            value = JSON.parse(readFileSync(this.path, "utf8"));
+            text = this.files.read(this.path, false);
         }
         catch (error) {
-            if (error.code === "ENOENT")
+            if (error instanceof AxiError)
+                throw error;
+            if (error.code === "ENOENT") {
+                if (existsSync(legacy))
+                    this.moved();
                 return { version: 1, profiles: {} };
-            invalid("Unable to read profile configuration; check the file permissions and version-1 JSON schema");
+            }
+            throw error;
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            invalid("Unable to read profile configuration; check the version-1 JSON schema");
         }
         if (!object(value) || value.version !== 1 || !exact(value, ["version", "defaultProfile", "profiles"]) || !object(value.profiles))
             invalid("Unsupported profile configuration; explicitly migrate to version 1");
@@ -106,80 +163,69 @@ export class Profiles {
         for (const [name, profile] of Object.entries(value.profiles)) {
             if (!namePattern.test(name))
                 invalid("Invalid profile name");
-            profiles[name] = validateProfile(profile);
+            profiles[name] = validateProfile(profile, this.files);
+            names.set(profiles[name], name);
         }
         if (value.defaultProfile !== undefined && (typeof value.defaultProfile !== "string" || !Object.hasOwn(profiles, value.defaultProfile)))
             invalid("Default profile does not exist");
-        if (new Set(Object.values(profiles).map(profile => profile.credentialRef.key)).size !== Object.keys(profiles).length)
-            invalid("Each profile must have a separate credential reference");
         return { version: 1, profiles, defaultProfile: value.defaultProfile };
     }
     list() { return Object.entries(this.load().profiles).map(([name, profile]) => ({ name, mode: profile.mode, tenant: profile.tenantId, cloud: profile.cloud })); }
     resolve(name) {
+        const flag = name !== undefined && name.trim() !== "" ? name.trim() : undefined;
+        const envName = process.env.MG_AXI_PROFILE !== undefined && process.env.MG_AXI_PROFILE.trim() !== "" ? process.env.MG_AXI_PROFILE.trim() : undefined;
+        const explicit = flag ?? envName;
+        if (explicit === undefined) {
+            const profile = envProfile(process.env);
+            if (profile) {
+                names.set(profile, "env");
+                return { name: "env", profile };
+            }
+        }
         const config = this.load();
-        const selected = name ?? config.defaultProfile;
-        if (!selected || !Object.hasOwn(config.profiles, selected))
-            throw new AxiError("No configured profile selected", "AUTH_REQUIRED", ["mg-axi profile list", "mg-axi profile create --help"]);
+        const configured = Object.keys(config.profiles);
+        const selected = explicit ?? config.defaultProfile ?? (configured.length === 1 ? configured[0] : undefined);
+        if (!selected)
+            throw new AxiError("No configured profile selected", configured.length ? "PROFILE_AMBIGUOUS" : "PROFILE_REQUIRED", ["mg-axi profile list", "mg-axi profile create --help"]);
+        if (!Object.hasOwn(config.profiles, selected))
+            throw new AxiError(`Profile ${selected} does not exist`, "PROFILE_NOT_FOUND", ["mg-axi profile list"]);
         return { name: selected, profile: config.profiles[selected] };
     }
+    verifyPermissions() {
+        try {
+            this.files.check(this.path, false, true);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
     create(name, tenantId, clientId, cloud, allowDeviceCode, application) {
         if (!namePattern.test(name))
             invalid("Profile name must contain only letters, digits, underscores or hyphens");
-        const certificate = application?.certificateThumbprint;
-        const federated = application?.federated ?? false;
-        const secretEnv = application?.clientSecretEnv;
-        const secretFile = application?.clientSecretFile;
-        const keyFile = application?.certificateKeyFile;
-        const keyEnv = application?.certificateKeyEnv;
-        const tokenFileEnv = application?.federatedTokenFileEnv;
-        if (application && (certificate !== undefined && (typeof certificate !== "string" || !/^[0-9a-f]{40}$/i.test(certificate))))
-            invalid("Application certificate profiles name a 40-hex-digit thumbprint; the private key stays in referenced storage");
-        for (const [label, value] of [["--client-secret-env", secretEnv], ["--certificate-key-env", keyEnv], ["--federated-token-file-env", tokenFileEnv]]) {
-            if (application && value !== undefined && (typeof value !== "string" || !envName.test(value)))
-                invalid(`Application profiles name the credential holder with ${label}; names match /^[A-Za-z_][A-Za-z0-9_]*$/`);
-        }
-        for (const [label, value] of [["--client-secret-file", secretFile], ["--certificate-key-file", keyFile]]) {
-            if (application && value !== undefined && !credentialPath(value))
-                invalid(`Application profiles name the credential holder with ${label}; paths must be nonempty`);
+        const base = { tenantId, clientId, cloud, allowDeviceCode };
+        let profile;
+        if (!application)
+            profile = validateDelegatedProfile({ ...base, mode: "delegated", token: { stored: true } }, this.files);
+        else {
+            const { certificateThumbprint, federated, clientSecretEnv, clientSecretFile, certificateKeyFile, certificateKeyEnv, federatedTokenFile } = application;
+            if (clientSecretEnv !== undefined && clientSecretFile !== undefined || certificateKeyEnv !== undefined && certificateKeyFile !== undefined)
+                invalid("Use exactly one env or file reference for each credential");
+            if ([certificateThumbprint !== undefined, federated === true, clientSecretEnv !== undefined || clientSecretFile !== undefined].filter(Boolean).length !== 1)
+                invalid("Select exactly one application credential kind");
+            if ((certificateKeyEnv !== undefined || certificateKeyFile !== undefined) && certificateThumbprint === undefined || federatedTokenFile !== undefined && !federated)
+                invalid("Credential holder does not match the selected application auth kind");
+            profile = validateApplicationProfile({ ...base, mode: "application",
+                ...(certificateThumbprint !== undefined ? { auth: "certificate", thumbprintSha256: certificateThumbprint, privateKey: certificateKeyFile !== undefined ? { file: certificateKeyFile } : { env: certificateKeyEnv ?? "MG_AXI_PRIVATE_KEY" } }
+                    : federated ? { auth: "federated", ...(federatedTokenFile === undefined ? {} : { token: { file: federatedTokenFile } }) }
+                        : { auth: "client-secret", clientSecret: clientSecretFile !== undefined ? { file: clientSecretFile } : { env: clientSecretEnv } }) }, this.files);
         }
-        if (application && secretEnv !== undefined && secretFile !== undefined)
-            invalid("Application client-secret profiles use exactly one holder: --client-secret-env or --client-secret-file");
-        if (application && keyFile !== undefined && keyEnv !== undefined)
-            invalid("Application certificate profiles use exactly one key holder: --certificate-key-file or --certificate-key-env; omit both for the OS keychain");
-        if (application && (keyFile !== undefined || keyEnv !== undefined) && certificate === undefined)
-            invalid("Certificate key holders need --certificate-thumbprint on the same profile");
-        if (application && tokenFileEnv !== undefined && !federated)
-            invalid("Federated token-file holders need --federated on the same profile");
-        if (application && [certificate !== undefined, secretEnv !== undefined || secretFile !== undefined, federated].filter(Boolean).length !== 1)
-            invalid("Application profiles use exactly one credential: --certificate-thumbprint, --client-secret-env/--client-secret-file or --federated");
-        if (application && allowDeviceCode)
-            invalid("Application profiles never use device code; it is a delegated login method");
-        const credentialRef = certificate === undefined
-            ? secretEnv === undefined && secretFile === undefined
-                ? { provider: "federated", key: randomUUID(), ...(tokenFileEnv === undefined ? {} : { tokenFileEnv }) }
-                : { provider: "client-secret", key: randomUUID(), ...(secretEnv === undefined ? { secretFile: secretFile } : { secretEnv }) }
-            : { provider: "certificate", key: randomUUID(), thumbprint: certificate, ...(keyFile === undefined && keyEnv === undefined ? {} : keyFile === undefined ? { keyEnv: keyEnv } : { keyFile }) };
-        const profile = application
-            ? validateApplicationProfile({ mode: "application", tenantId, clientId, cloud, enabledPacks: ["entra"], preview: false, sensitiveAreas: [],
-                credentialRef, allowDeviceCode: false })
-            : validateDelegatedProfile({ mode: "delegated", tenantId, clientId, cloud, enabledPacks: ["entra"], preview: false, sensitiveAreas: [], credentialRef: { provider: "os-or-session", key: randomUUID() }, allowDeviceCode });
         const config = this.load();
         if (Object.hasOwn(config.profiles, name))
             invalid("Profile already exists; creation never replaces identity");
         config.profiles[name] = profile;
         config.defaultProfile ??= name;
-        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
-        const temporary = `${this.path}.${randomUUID()}.tmp`;
-        try {
-            writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
-            renameSync(temporary, this.path);
-        }
-        catch {
-            throw new AxiError("Unable to save profile configuration", "CONFIG_ERROR", ["Check configuration directory permissions"]);
-        }
-        finally {
-            rmSync(temporary, { force: true });
-        }
+        this.files.write(this.path, `${JSON.stringify(config, null, 2)}\n`);
         return { name, mode: profile.mode, tenant: profile.tenantId, cloud: profile.cloud };
     }
 }

package/dist/redact.js

@@ -0,0 +1,26 @@
+const secrets = new Set();
+export function registerSecret(value) {
+    if (!value)
+        return value;
+    for (const form of [value, JSON.stringify(value).slice(1, -1), encodeURIComponent(value)])
+        secrets.add(form);
+    return value;
+}
+export function redactSecrets(value) {
+    for (const secret of [...secrets].sort((a, b) => b.length - a.length))
+        value = value.split(secret).join("***redacted***");
+    return value;
+}
+// MSAL caches contain opaque refresh, access and ID tokens under secret fields.
+export function registerCache(value) {
+    registerSecret(value);
+    const visit = (entry, key = "") => {
+        if (typeof entry === "string" && /^(secret|accessToken|refreshToken|idToken)$/i.test(key))
+            registerSecret(entry);
+        else if (entry && typeof entry === "object")
+            for (const [name, child] of Object.entries(entry))
+                visit(child, name);
+    };
+    visit(JSON.parse(value));
+    return value;
+}

package/dist/secrets.js

@@ -0,0 +1,37 @@
+import { AxiError } from "axi-sdk-js";
+import { PrivateFiles } from "./private-file.js";
+import { registerSecret } from "./redact.js";
+export function validateSecretRef(value, field, stored = true, files = new PrivateFiles()) {
+    if (value === undefined)
+        return Object.freeze({ env: `MG_AXI_${field.replace(/[A-Z]/g, letter => `_${letter}`).toUpperCase()}` });
+    if (value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 1) {
+        const ref = value;
+        if (typeof ref.env === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(ref.env))
+            return Object.freeze({ env: ref.env });
+        if (typeof ref.file === "string" && files.absolute(ref.file))
+            return Object.freeze({ file: ref.file });
+        if (stored && ref.stored === true)
+            return Object.freeze({ stored: true });
+    }
+    throw new AxiError(`Invalid ${field}; use a SecretRef, never an inline secret`, "CONFIG_INVALID", ["Use exactly one validated env name, absolute local file path, or stored: true for a delegated login"]);
+}
+export function secretSource(ref) { return "env" in ref ? `env:${ref.env}` : "file" in ref ? `file:${ref.file}` : "stored"; }
+export function resolveSecret(ref, files = new PrivateFiles(), verifyAcl = false) {
+    let value;
+    if ("env" in ref)
+        value = process.env[ref.env];
+    else if ("file" in ref) {
+        try {
+            value = files.read(ref.file, true, verifyAcl).trimEnd();
+        }
+        catch (error) {
+            if (error instanceof AxiError)
+                throw error;
+            if (error?.code !== "ENOENT")
+                throw error;
+        }
+    }
+    if (!value?.trim())
+        throw new AxiError(`Credential unavailable from ${secretSource(ref)}`, "AUTH_REQUIRED", ["Supply the named credential reference; no interactive fallback was attempted"]);
+    return registerSecret(value);
+}

package/dist/setup.js

@@ -105,9 +105,9 @@ export function setupView(store) {
             "node dist/bin/mg-axi.js --version",
         ],
         guidance: [
-            `Hand-edit ${store.path} or set MG_AXI_CONFIG to a separate configuration file; a profile stores only a credential reference - an OS keychain entry, an environment variable name, or a file path - and never the secret value, never in argv or config`,
+            `Hand-edit ${store.path} or set MG_AXI_CONFIG to a separate configuration file; a profile stores only a SecretRef - an environment variable name, an absolute file path, or stored: true for delegated login - and never the secret value, never in argv or config`,
             "node dist/bin/mg-axi.js profile create --name soc --tenant <tenant-id> --client <client-id> --cloud commercial",
-            "node dist/bin/mg-axi.js login --profile soc --scopes https://graph.microsoft.com/User.Read.All",
+            "node dist/bin/mg-axi.js auth login --profile soc --scopes https://graph.microsoft.com/User.Read.All",
             "node dist/bin/mg-axi.js doctor",
         ],
         capabilities: {

package/docs/coverage.md

@@ -14,7 +14,7 @@ scheduled work as complete.
 
 - implemented read leaves: 263 (261 named Entra reads plus reviewed raw api get and doctor health check)
 - implemented write leaves: 5 (named gated mutations below)
-- local leaves: 7 (home, profile, login and setup views)
+- local leaves: 11 (home, profile, config, auth, login alias and setup views)
 - inventory named-command: 289
 - inventory reviewed-raw-read: 5
 - inventory scheduled: 3717

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/mg-axi",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Agent-facing Microsoft Graph CLI, read-only by default",
   "type": "module",
   "bin": {
@@ -20,7 +20,8 @@
     "inventory/operations.json",
     "skills/mg-axi",
     "docs/coverage.md",
-    "README.md"
+    "README.md",
+    "axi-credential.schema.json"
   ],
   "engines": {
     "node": ">=22.12.0"
@@ -28,7 +29,7 @@
   "packageManager": "pnpm@10.34.6",
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node --test --test-concurrency=4 test/*.test.mjs",
+    "test": "node tools/isolated-home.mjs node --test --test-concurrency=4 test/*.test.mjs",
     "lint": "tsc --noEmit -p tsconfig.json",
     "docs:generate": "node tools/generate-docs.mjs",
     "docs:check": "node tools/generate-docs.mjs --check"
@@ -42,8 +43,5 @@
   "devDependencies": {
     "@types/node": "^22.20.5",
     "typescript": "^7.0.2"
-  },
-  "optionalDependencies": {
-    "keytar": "^7.9.0"
   }
 }

package/skills/mg-axi/SKILL.md

@@ -17,13 +17,13 @@ See [README.md](../../README.md) for write usage, execution gates, identity pinn
 Run commands non-interactively as `npx -y @knowttl/mg-axi ...`: no global install needed and no interactive prompts.
 Version pinning is the installer's choice: use `npx -y @knowttl/mg-axi@<version> ...` to select a specific release.
 Run `npx -y @knowttl/mg-axi doctor` first.
-See [README.md](../../README.md#release) for doctor profile selection, checks and failure behavior.
+See [README.md](../../README.md#usage) for doctor profile selection, checks and failure behavior.
 
 ## Orientation
 
 The exact current leaf registry is `src/catalogue.ts`.
 Its capability label is `native` (implemented by an mg-axi handler).
-Its effect is `read` for Graph read leaves and the doctor health check, `write` for the gated named writes, or `local` for home, profile, login and setup views.
+Its effect is `read` for Graph read leaves and the doctor health check, `write` for the gated named writes, or `local` for home, profile, auth, config path, login-alias and setup views.
 Doctor acquires credentials silently and contacts Graph; only its help view stays offline.
 The list below records current executable leaves; it makes no coverage claim for other Graph operations.
 See `docs/coverage.md` for the per-operation disposition records.
@@ -36,7 +36,7 @@ See `docs/coverage.md` for the per-operation disposition records.
 | `mg-axi profile create` | native | local |
 | `mg-axi profile list` | native | local |
 | `mg-axi profile show` | native | local |
-| `mg-axi login` | native | local |
+| `mg-axi auth login` | native | local |
 | `mg-axi setup` | native | local |
 | `mg-axi setup hooks` | native | local |
 | `mg-axi doctor` | native | read |
@@ -307,6 +307,10 @@ See `docs/coverage.md` for the per-operation disposition records.
 | `mg-axi entra lifecycle run task-processing-result show` | native | read |
 | `mg-axi entra lifecycle run task-processing-result count` | native | read |
 | `mg-axi api get` | native | read |
+| `mg-axi login` | native | local |
+| `mg-axi config path` | native | local |
+| `mg-axi auth status` | native | local |
+| `mg-axi auth logout` | native | local |
 <!-- command-registry:end -->
 
 Run `npx -y @knowttl/mg-axi <leaf-path> --help` for that leaf's accepted flags and reference.
@@ -318,7 +322,7 @@ The no-args home view prints these hints alongside live profile status:
 
 ```sh
 npx -y @knowttl/mg-axi profile list
-npx -y @knowttl/mg-axi login --help
+npx -y @knowttl/mg-axi auth login --help
 npx -y @knowttl/mg-axi setup
 npx -y @knowttl/mg-axi doctor
 npx -y @knowttl/mg-axi entra user list --help
@@ -333,18 +337,18 @@ npx -y @knowttl/mg-axi api get --help
 
 ## Setup (explicit only)
 
-Follow [release guidance](../../README.md#release) for npm installation and explicit skill installation; [README.md](../../README.md#mg-axi) also documents checkout builds.
+Follow [installation guidance](../../README.md#quick-start) for npm installation and explicit skill installation; [README.md](../../README.md#development--testing) also documents checkout builds.
 Create profiles explicitly and keep secrets out of argv and config files:
 
 ```sh
 npx -y @knowttl/mg-axi setup                    # build steps, config path and capabilities; writes nothing
 npx -y @knowttl/mg-axi profile create --name soc --tenant <tenant-id> --client <client-id> --cloud commercial
-npx -y @knowttl/mg-axi login --profile soc --scopes https://graph.microsoft.com/User.Read.All
+npx -y @knowttl/mg-axi auth login --profile soc --scopes https://graph.microsoft.com/User.Read.All
 npx -y @knowttl/mg-axi doctor                   # one bounded read per selected profile
 npx -y @knowttl/mg-axi entra user list --profile soc --limit 10
 ```
 
-Configuration defaults to `~/.mg-axi/config.json`; `MG_AXI_CONFIG` selects a separate file.
+Configuration uses the XDG config directory (default `~/.config/mg-axi/config.json`), or `%APPDATA%\mg-axi\config.json` on Windows; `--config` overrides `MG_AXI_CONFIG`.
 `mg-axi setup` shows the selected path and writes nothing.
 Application profiles authenticate headlessly through credential references: the profile names an env var or file and the environment supplies the value at acquisition time.
 Container examples for client secrets, certificate keys and workload federation live in [README.md](../../README.md#mg-axi).
@@ -366,14 +370,13 @@ No other ordinary command installs hooks, plugins or configuration.
 ## Selecting a profile
 
 Read leaves accept `--profile <name>`.
-Selection uses `--profile` or the configured default.
-Without either, read leaves report `AUTH_REQUIRED`, even if only one profile exists.
-Doctor selection is documented in [README.md](../../README.md#release).
+Profile selection order and env-profile rules live in [README Configuration](../../README.md#configuration); an explicitly selected file profile ignores env fields.
+Doctor selection is documented in [README.md](../../README.md#usage).
 Without profiles, home, setup and profile list show unconfigured state; Graph read leaves report `AUTH_REQUIRED`.
 
 ## Safety
 
-Reads run through a session that authorizes only catalogued operations before silent credential acquisition; only explicit `login` opens a browser or prints a device-code challenge.
+Reads run through a session that authorizes only catalogued operations before silent credential acquisition; only explicit `auth login` opens a browser or prints a device-code challenge.
 Writes preview before sending and need `--execute` plus a typed `--confirm` repeating the target; an already-desired value is a no-op with exit 0, never an error.
 Output is TOON on stdout; diagnostics use stderr.
 Text truncates at 500 characters (`--full` restores text, never redaction); row caps resume through opaque cursors.