@knowttl/mg-axi 0.1.3 → 0.1.6

package/axi-credential.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "mg-axi credential profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mode", "tenantId", "clientId"],
+  "properties": {
+    "mode": { "enum": ["delegated", "application"] },
+    "tenantId": { "$ref": "#/$defs/uuid" },
+    "clientId": { "$ref": "#/$defs/uuid" },
+    "cloud": { "const": "commercial", "default": "commercial" },
+    "enabledPacks": { "type": "array", "items": { "const": "entra" }, "uniqueItems": true, "default": ["entra"] },
+    "preview": { "type": "boolean", "default": false },
+    "sensitiveAreas": { "type": "array", "maxItems": 0, "default": [] },
+    "allowDeviceCode": { "type": "boolean", "default": false },
+    "auth": { "enum": ["certificate", "client-secret", "federated"] },
+    "thumbprintSha256": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" },
+    "privateKey": { "$ref": "#/$defs/externalSecret", "x-secret": true },
+    "clientSecret": { "$ref": "#/$defs/externalSecret", "x-secret": true },
+    "token": { "$ref": "#/$defs/secret", "x-secret": true },
+    "writes": {
+      "type": "object", "additionalProperties": false, "required": ["allowWrites", "operations"],
+      "properties": {
+        "allowWrites": { "type": "boolean" },
+        "operations": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "string", "minLength": 1, "maxLength": 256 } }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "properties": { "mode": { "const": "delegated" } },
+      "not": { "anyOf": [{ "required": ["auth"] }, { "required": ["privateKey"] }, { "required": ["clientSecret"] }, { "required": ["thumbprintSha256"] }] }
+    },
+    {
+      "required": ["auth", "thumbprintSha256"],
+      "properties": { "mode": { "const": "application" }, "auth": { "const": "certificate" }, "allowDeviceCode": { "const": false } },
+      "not": { "anyOf": [{ "required": ["token"] }, { "required": ["clientSecret"] }] }
+    },
+    {
+      "required": ["auth"],
+      "properties": { "mode": { "const": "application" }, "auth": { "const": "client-secret" }, "allowDeviceCode": { "const": false } },
+      "not": { "anyOf": [{ "required": ["token"] }, { "required": ["privateKey"] }, { "required": ["thumbprintSha256"] }] }
+    },
+    {
+      "required": ["auth"],
+      "properties": { "mode": { "const": "application" }, "auth": { "const": "federated" }, "token": { "$ref": "#/$defs/externalSecret" }, "allowDeviceCode": { "const": false } },
+      "not": { "anyOf": [{ "required": ["privateKey"] }, { "required": ["clientSecret"] }, { "required": ["thumbprintSha256"] }] }
+    }
+  ],
+  "$defs": {
+    "uuid": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" },
+    "externalSecret": {
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["env"], "properties": { "env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
+        { "type": "object", "additionalProperties": false, "required": ["file"], "properties": { "file": { "type": "string", "pattern": "^(?:/|[A-Za-z]:[\\\\/])" } } }
+      ]
+    },
+    "secret": {
+      "oneOf": [
+        { "$ref": "#/$defs/externalSecret" },
+        { "type": "object", "additionalProperties": false, "required": ["stored"], "properties": { "stored": { "const": true } } }
+      ]
+    }
+  }
+}

package/dist/app-auth.js

@@ -1,5 +1,7 @@
 import { AxiError } from "axi-sdk-js";
+import { PrivateFiles } from "./private-file.js";
 import { validateApplicationProfile } from "./profiles.js";
+import { registerSecret } from "./redact.js";
 // The configured Graph audience is the app's consented application grants, never a per-command subset.
 export const graphAudience = (profile) => `https://graph.microsoft.com/.default`;
 // This service is the application credential boundary for CORE-01; tokens never reach CLI output.
@@ -7,13 +9,15 @@ export const graphAudience = (profile) => `https://graph.microsoft.com/.default`
 export class ApplicationAuth {
     provider;
     now;
+    files;
     cache = new Map();
-    constructor(provider, now = Date.now) {
+    constructor(provider, now = Date.now, files = new PrivateFiles()) {
         this.provider = provider;
         this.now = now;
+        this.files = files;
     }
     async credential(profile, scopes = [graphAudience(profile)]) {
-        profile = validateApplicationProfile(profile);
+        profile = validateApplicationProfile(profile, this.files);
         const requested = this.audience(profile, scopes);
         const key = this.key(profile, requested);
         const hit = this.cache.get(key);
@@ -27,7 +31,11 @@ export class ApplicationAuth {
             this.cache.set(key, credential);
             return { ...credential };
         }
-        catch {
+        catch (error) {
+            // Provider AUTH_REQUIRED failures already name only the credential
+            // reference, never its value; everything else stays fully generic.
+            if (error instanceof AxiError && ["AUTH_REQUIRED", "CONFIG_INVALID", "CONFIG_INSECURE"].includes(error.code))
+                throw error;
             throw this.failure();
         }
     }
@@ -37,10 +45,11 @@ export class ApplicationAuth {
             throw new AxiError("Application profiles use the configured Graph .default audience; delegated scopes are unavailable", "VALIDATION_ERROR", ["mg-axi profile show --profile <name>", "Application permissions apply to the app registration, not to individual commands"]);
         return configured;
     }
-    key(profile, scopes) { return JSON.stringify([profile.credentialRef, profile.tenantId, profile.clientId, profile.cloud, scopes]); }
+    key(profile, scopes) { return JSON.stringify([profile.auth, profile.auth === "certificate" ? [profile.privateKey, profile.thumbprintSha256] : profile.auth === "client-secret" ? profile.clientSecret : profile.token, profile.tenantId, profile.clientId, profile.cloud, scopes]); }
     check(profile, credential) {
         if (!credential.token || credential.tenantId.toLowerCase() !== profile.tenantId.toLowerCase() || credential.clientId.toLowerCase() !== profile.clientId.toLowerCase() || !Number.isFinite(credential.expiresAt) || credential.expiresAt <= this.now() + 60_000)
             throw new Error("Invalid credential context");
+        registerSecret(credential.token);
         return { ...credential };
     }
     failure() { return new AxiError("Application authentication failed for the configured identity; no user or device-code fallback was attempted", "AUTH_REQUIRED", ["mg-axi profile show --profile <name>", "Ask an administrator to grant application consent for the Graph .default audience on this app registration", "Confirm the certificate thumbprint or federated credential mapping on the app registration"]); }

package/dist/auth-status.js

@@ -0,0 +1,20 @@
+import { AxiError } from "axi-sdk-js";
+import { Credentials } from "./credentials.js";
+import { resolveSecret, secretSource } from "./secrets.js";
+export function authStatus(name, profile, credentials = new Credentials()) {
+    const fields = profile.mode === "delegated" ? { token: profile.token }
+        : profile.auth === "certificate" ? { privateKey: profile.privateKey }
+            : profile.auth === "client-secret" ? { clientSecret: profile.clientSecret } : { token: profile.token };
+    const sources = Object.entries(fields).map(([field, ref]) => {
+        let available = false;
+        try {
+            available = "stored" in ref && profile.mode === "delegated" ? credentials.read(profile, true) !== undefined : !!resolveSecret(ref, credentials.files, true);
+        }
+        catch (error) {
+            if (!(error instanceof AxiError) || error.code !== "AUTH_REQUIRED")
+                throw error;
+        }
+        return { field, source: "stored" in ref ? `stored:${credentials.path}` : secretSource(ref), available };
+    });
+    return { profile: name, mode: profile.mode, endpoint: "https://graph.microsoft.com", tenantId: profile.tenantId, clientId: profile.clientId, sources };
+}

package/dist/auth.js

@@ -1,18 +1,22 @@
 import { AxiError } from "axi-sdk-js";
-import { validateDelegatedProfile } from "./profiles.js";
+import { PrivateFiles } from "./private-file.js";
+import { profileName, validateDelegatedProfile } from "./profiles.js";
+import { registerSecret } from "./redact.js";
 // This service is the credential boundary for CORE-01; tokens never reach CLI output.
 export class DelegatedAuth {
     provider;
     now;
+    files;
     cache = new Map();
-    constructor(provider, now = Date.now) {
+    constructor(provider, now = Date.now, files = new PrivateFiles()) {
         this.provider = provider;
         this.now = now;
+        this.files = files;
     }
     async login(profile, method = "browser", scopes = []) {
-        profile = validateDelegatedProfile(profile);
+        profile = validateDelegatedProfile(profile, this.files);
         if (method !== "browser" && method !== "device-code")
-            throw new AxiError("Login method must be browser or device-code", "VALIDATION_ERROR", ["mg-axi login --help"]);
+            throw new AxiError("Login method must be browser or device-code", "VALIDATION_ERROR", ["mg-axi auth login --help"]);
         if (method === "device-code" && !profile.allowDeviceCode)
             throw new AxiError("Device code is disabled for this profile", "VALIDATION_ERROR", ["Enable device code only when organization policy permits it; browser login is the default"]);
         const requested = this.scopes(scopes);
@@ -23,12 +27,14 @@ export class DelegatedAuth {
             this.cache.set(key, credential);
             return { status: "authenticated", mode: "delegated", storage: this.provider.storage };
         }
-        catch {
+        catch (error) {
+            if (error instanceof AxiError && ["CONFIG_INVALID", "CONFIG_INSECURE"].includes(error.code))
+                throw error;
             throw this.failure("LOGIN_FAILED");
         }
     }
     async credential(profile, scopes) {
-        profile = validateDelegatedProfile(profile);
+        profile = validateDelegatedProfile(profile, this.files);
         const requested = this.scopes(scopes);
         const key = this.key(profile, requested);
         const hit = this.cache.get(key);
@@ -40,20 +46,28 @@ export class DelegatedAuth {
             this.cache.set(key, credential);
             return { ...credential };
         }
-        catch {
+        catch (error) {
+            if (error instanceof AxiError && ["CONFIG_INVALID", "CONFIG_INSECURE"].includes(error.code))
+                throw error;
             throw this.failure("AUTH_REQUIRED");
         }
     }
+    async logout(profile) {
+        this.cache.clear();
+        await this.provider.logout(validateDelegatedProfile(profile, this.files));
+        return { status: "signed out", revocation: "MSAL provides no token revocation API; local credentials deleted" };
+    }
     scopes(scopes) {
         if (!scopes.length || scopes.some(scope => !/^https:\/\/graph\.microsoft\.com\/[A-Za-z][A-Za-z.-]+$/.test(scope) || scope.endsWith("/.default")))
-            throw new AxiError("Explicit delegated Graph scopes are required", "VALIDATION_ERROR", ["mg-axi login --profile <name> --scopes <comma-separated-Graph-scopes>"]);
+            throw new AxiError("Explicit delegated Graph scopes are required", "VALIDATION_ERROR", ["mg-axi auth login --profile <name> --scopes <comma-separated-Graph-scopes>"]);
         return [...new Set(scopes)].sort();
     }
-    key(profile, scopes) { return JSON.stringify([profile.credentialRef, profile.tenantId, profile.clientId, profile.cloud, scopes]); }
+    key(profile, scopes) { return JSON.stringify([profileName(profile), profile.token, profile.tenantId, profile.clientId, profile.cloud, scopes]); }
     check(profile, credential) {
         if (!credential.token || !credential.accountId || credential.tenantId.toLowerCase() !== profile.tenantId.toLowerCase() || credential.clientId.toLowerCase() !== profile.clientId.toLowerCase() || !Number.isFinite(credential.expiresAt) || credential.expiresAt <= this.now() + 60_000)
             throw new Error("Invalid credential context");
+        registerSecret(credential.token);
         return { ...credential };
     }
-    failure(code) { return new AxiError("Authentication unavailable for the configured identity; no interactive fallback was attempted", code, ["mg-axi login --profile <name> --scopes <comma-separated-Graph-scopes>", "Check dedicated app consent and organization sign-in policy", "Restore OS credential store access before retrying login; prior stored accounts must be invalidated before replacement"]); }
+    failure(code) { return new AxiError("Authentication unavailable for the configured identity; no interactive fallback was attempted", code, ["mg-axi auth login --profile <name> --scopes <comma-separated-Graph-scopes>", "Check dedicated app consent and organization sign-in policy", "Restore access to the protected credentials.json before retrying login"]); }
 }

package/dist/catalogue.js

@@ -506,18 +506,23 @@ export const LEAVES = [
             cloud: { value: "commercial", required: true, description: "Explicit cloud; only commercial is supported" },
             mode: { value: "delegated|application", default: "delegated", description: "Delegated analyst sign-in or application client credentials" },
             "allow-device-code": { description: "Delegated only: opt in only when permitted by organization policy; never enables fallback" },
-            "certificate-thumbprint": { value: "40-hex-digits", description: "Application only: certificate thumbprint; the private key stays in protected storage" },
-            federated: { description: "Application only: workload federation via the AZURE_FEDERATED_TOKEN_FILE assertion source" },
-        }, examples: ["mg-axi profile create --name soc --tenant <tenant-id> --client <client-id> --cloud commercial", "mg-axi profile create --name batch --tenant <tenant-id> --client <client-id> --cloud commercial --mode application --federated", "mg-axi profile create --help"] },
+            "certificate-thumbprint-sha256": { value: "64-hex-digits", description: "Application only: SHA-256 certificate thumbprint" },
+            "certificate-key-file": { value: "absolute-path", description: "Application only: certificate PEM private key from this protected file" },
+            "certificate-key-env": { value: "env-var-name", description: "Application only: certificate PEM private key from this environment variable; defaults to MG_AXI_PRIVATE_KEY" },
+            "client-secret-env": { value: "env-var-name", description: "Application only: client secret from this environment variable; exactly one of this or --client-secret-file" },
+            "client-secret-file": { value: "absolute-path", description: "Application only: client secret from this protected file; exactly one of this or --client-secret-env" },
+            federated: { description: "Application only: workload federation; token defaults to env MG_AXI_TOKEN; AZURE_FEDERATED_TOKEN_FILE stays accepted as a deprecated alias" },
+            "federated-token-file": { value: "absolute-path", description: "Application only: workload assertion content from this protected file" },
+        }, examples: ["mg-axi profile create --name soc --tenant <tenant-id> --client <client-id> --cloud commercial", "mg-axi profile create --name batch --tenant <tenant-id> --client <client-id> --cloud commercial --mode application --federated", "mg-axi profile create --name daemon --tenant <tenant-id> --client <client-id> --cloud commercial --mode application --certificate-thumbprint-sha256 <64-hex-digit-thumbprint> --certificate-key-file /run/secrets/mg-axi-key.pem", "mg-axi profile create --name svc --tenant <tenant-id> --client <client-id> --cloud commercial --mode application --client-secret-env MG_AXI_CLIENT_SECRET", "mg-axi profile create --help"] },
     { path: "profile list", description: "List configured profiles without accessing credentials", flags: {}, examples: ["mg-axi profile list", "mg-axi profile list --help"] },
     { path: "profile show", description: "Show profile policy and credential reference, never credentials", flags: {
             profile: common.profile,
         }, examples: ["mg-axi profile show --profile soc", "mg-axi profile show"] },
-    { path: "login", description: "Explicit delegated login; browser by default, no automatic device-code fallback", flags: {
+    { path: "auth login", description: "Explicit delegated login; browser by default, no automatic device-code fallback", flags: {
             profile: common.profile,
             method: { value: "browser|device-code", default: "browser", description: "Device code additionally requires profile opt-in" },
             scopes: { value: "comma-separated-Graph-scopes", required: true, description: "Explicit delegated permissions using full https://graph.microsoft.com/ scope names" },
-        }, examples: ["mg-axi login --profile soc --scopes https://graph.microsoft.com/User.Read", "mg-axi login --profile soc --method device-code --scopes https://graph.microsoft.com/User.Read"] },
+        }, examples: ["mg-axi auth login --profile soc --scopes https://graph.microsoft.com/User.Read", "mg-axi auth login --profile soc --method device-code --scopes https://graph.microsoft.com/User.Read"] },
     { path: "setup", description: "Show installation, configuration and capability guidance without signing in or writing anything", flags: {}, examples: ["mg-axi setup", "mg-axi setup --help"] },
     { path: "setup hooks", description: "Install or repair agent SessionStart hooks for mg-axi ambient context", flags: {}, examples: ["mg-axi setup hooks", "mg-axi setup hooks --help"] },
     { path: "doctor", description: "Check each selected profile with one bounded user-list read; never signs in interactively, installs nothing, enables no writes", flags: {
@@ -2785,6 +2790,12 @@ export const LEAVES = [
             full: { description: "Disable 500-character string truncation; never disables redaction or row caps" },
         }, examples: ["mg-axi api get /users --scopes https://graph.microsoft.com/User.Read.All", "mg-axi api get /groups --odata '$filter=securityEnabled eq true&$top=5' --scopes https://graph.microsoft.com/GroupMember.Read.All", "mg-axi api get /users --cursor - --all --scopes https://graph.microsoft.com/User.Read.All < cursor.txt"] },
 ];
+LEAVES.push({ ...LEAVES.find(leaf => leaf.path === "auth login"), path: "login", description: "Deprecated alias for auth login (one minor release)" });
+LEAVES.push({ path: "config path", description: "Show the selected configuration path without reading credentials", flags: {}, examples: ["mg-axi config path", "mg-axi config path --config /absolute/path/config.json"] });
+LEAVES.push({ path: "auth status", description: "Show credential sources and verify local file permissions without a live request", flags: { profile: common.profile }, examples: ["mg-axi auth status", "mg-axi auth status --profile soc"] });
+LEAVES.push({ path: "auth logout", description: "Delete the selected delegated login cache without prompting", flags: { profile: common.profile }, examples: ["mg-axi auth logout", "mg-axi auth logout --profile soc"] });
+for (const leaf of LEAVES)
+    leaf.flags.config = { value: "path", description: "Configuration file override; takes precedence over MG_AXI_CONFIG" };
 export function leafHelp(leaf) {
     return [
         `mg-axi ${leaf.path}${leaf.positional ? ` <${leaf.positional.name}>` : ""}`, leaf.description,
@@ -2823,7 +2834,7 @@ export function resolveCommand(argv) {
     const flags = Object.create(null);
     for (let i = flagStart; i < argv.length; i++) {
         const arg = argv[i];
-        const match = /^--([a-z-]+)(?:=(.*))?$/.exec(arg);
+        const match = /^--([a-z][a-z0-9-]*)(?:=(.*))?$/.exec(arg);
         if (!match)
             fail("unexpected argument or short flag");
         const name = match[1];

package/dist/cli.js

@@ -1,10 +1,13 @@
 import { encode } from "@toon-format/toon";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, isAbsolute, sep } from "node:path";
 import { AxiError, installSessionStartHooks, runAxiCli } from "axi-sdk-js";
 import { LEAVES, home, leafHelp, operationFor, resolveCommand, DESCRIPTION, TOP_LEVEL_HELP } from "./catalogue.js";
 import { VERSION } from "./version.js";
 import { Profiles } from "./profiles.js";
+import { authStatus } from "./auth-status.js";
+import { redactSecrets } from "./redact.js";
 import { GraphSession, MAX_CURSOR_BYTES } from "./graph-session.js";
 import { listUsers, showUser } from "./entra-users.js";
 import { updateUserAccount } from "./entra-user-update.js";
@@ -48,22 +51,21 @@ import { addGroupMember } from "./entra-group-member-add.js";
 import { fetchTransport } from "./api.js";
 import { doctorTargets, runDoctor } from "./doctor.js";
 import { setupView } from "./setup.js";
-function localHome(name) {
+function localHome(name, config) {
     const output = home();
-    const store = new Profiles();
-    if (name || store.list().length) {
-        try {
-            const selected = store.resolve(name);
-            output.profile = selected.name;
-            output.tenant = selected.profile.tenantId;
-        }
-        catch (error) {
-            if (name || !(error instanceof AxiError) || error.code !== "AUTH_REQUIRED")
-                throw error;
+    const store = new Profiles(config);
+    try {
+        const selected = store.resolve(name);
+        output.profile = selected.name;
+        output.tenant = selected.profile.tenantId;
+    }
+    catch (error) {
+        if ((name?.trim() ? name : undefined) || !(error instanceof AxiError) || !["PROFILE_REQUIRED", "PROFILE_AMBIGUOUS"].includes(error.code))
+            throw error;
+        if (error.code === "PROFILE_AMBIGUOUS")
             output.profile = "unavailable: no default profile selected";
-        }
     }
-    output.help.unshift("npx -y @knowttl/mg-axi profile list", "npx -y @knowttl/mg-axi login --help");
+    output.help.unshift("npx -y @knowttl/mg-axi profile list", "npx -y @knowttl/mg-axi auth login --help");
     return output;
 }
 // One dispatch for the hook installer: resolve the sibling hook entry point
@@ -73,17 +75,34 @@ function localHome(name) {
 // summary from src/hook.ts. Install failures throw loudly; hook failures
 // never do.
 function runSetupHooks() {
-    const hookPath = join(dirname(process.argv[1] ?? ""), "mg-axi-hook.js");
+    const hookPath = join(dirname(realpathSync(process.argv[1] ?? "")), "mg-axi-hook.js");
     if (!existsSync(hookPath)) {
         throw new AxiError("Cannot locate the mg-axi-hook entry point", "HOOK_INSTALL_FAILED", [
             "Reinstall @knowttl/mg-axi so dist/bin/mg-axi-hook.js sits next to the main entry point",
             "Run mg-axi setup hooks again after reinstalling",
         ]);
     }
+    const target = realpathSync(hookPath);
+    const temporaryRoots = [tmpdir(), "/tmp", "/var/tmp"].map(path => existsSync(path) ? realpathSync(path) : path);
+    const inTemporaryDirectory = temporaryRoots.some(root => {
+        const path = relative(root, target);
+        return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+    });
+    let inWorktree = false;
+    for (let directory = dirname(target); directory !== dirname(directory); directory = dirname(directory)) {
+        const gitPath = join(directory, ".git");
+        if (existsSync(gitPath) && statSync(gitPath).isFile())
+            inWorktree = true;
+    }
+    if (inTemporaryDirectory || inWorktree || /(?:^|[/\\])(?:\.no-mistakes|\.treehouse|worktrees)(?:[/\\]|$)/.test(target)) {
+        throw new AxiError("Cannot install hooks from a temporary directory or worktree", "HOOK_INSTALL_FAILED", [
+            "Install @knowttl/mg-axi globally, then run mg-axi setup hooks from that installation",
+        ]);
+    }
     const failures = [];
     installSessionStartHooks({
         marker: "mg-axi-hook",
-        execPath: hookPath,
+        execPath: target,
         binaryNames: ["mg-axi-hook"],
         distEntrypoints: ["dist/bin/mg-axi-hook.js"],
         onError: (message) => { failures.push(message); },
@@ -115,21 +134,30 @@ export async function executeArgv(argv, overrides = {}) {
     if (flags.help)
         return leafHelp(leaf);
     if (leaf.path === "home")
-        return localHome(flags.profile);
-    const profiles = new Profiles();
+        return localHome(flags.profile, flags.config);
+    const profiles = new Profiles(flags.config);
+    if (leaf.path === "config path")
+        return { config: profiles.path };
     if (leaf.path === "profile create") {
-        if (String(flags.mode ?? "delegated") !== "application" && (flags["certificate-thumbprint"] !== undefined || flags.federated))
-            throw new AxiError("Certificate and federated credentials belong to application profiles; pass --mode application", "VALIDATION_ERROR", [leafHelp(leaf)]);
+        const credentialFlags = ["certificate-thumbprint-sha256", "client-secret-env", "client-secret-file", "certificate-key-file", "certificate-key-env", "federated-token-file"];
+        if (String(flags.mode ?? "delegated") !== "application" && (flags.federated || credentialFlags.some(name => flags[name] !== undefined)))
+            throw new AxiError("Certificate, client-secret and federated credentials belong to application profiles; pass --mode application", "VALIDATION_ERROR", [leafHelp(leaf)]);
+        const optional = (name) => flags[name] === undefined ? undefined : String(flags[name]);
         return profiles.create(String(flags.name), String(flags.tenant), String(flags.client), String(flags.cloud), !!flags["allow-device-code"], String(flags.mode ?? "delegated") === "application"
-            ? { certificateThumbprint: flags["certificate-thumbprint"] === undefined ? undefined : String(flags["certificate-thumbprint"]), federated: !!flags.federated }
+            ? { certificateThumbprint: optional("certificate-thumbprint-sha256"), federated: !!flags.federated, clientSecretEnv: optional("client-secret-env"), clientSecretFile: optional("client-secret-file"), certificateKeyFile: optional("certificate-key-file"), certificateKeyEnv: optional("certificate-key-env"), federatedTokenFile: optional("federated-token-file") }
             : undefined);
     }
     if (leaf.path === "profile list") {
         const items = profiles.list();
-        return items.length ? { profiles: items, help: ["npx -y @knowttl/mg-axi profile show --profile <name>", "npx -y @knowttl/mg-axi login --help"] } : { profiles: "0 profiles configured", help: ["npx -y @knowttl/mg-axi profile create --help"] };
+        return items.length ? { profiles: items, help: ["npx -y @knowttl/mg-axi profile show --profile <name>", "npx -y @knowttl/mg-axi auth login --help"] } : { profiles: "0 profiles configured", help: ["npx -y @knowttl/mg-axi profile create --help"] };
     }
     if (leaf.path === "profile show")
         return profiles.resolve(flags.profile);
+    if (leaf.path === "auth status") {
+        const selected = profiles.resolve(flags.profile);
+        profiles.verifyPermissions();
+        return authStatus(selected.name, selected.profile);
+    }
     if (leaf.path === "setup")
         return setupView(profiles);
     if (leaf.path === "setup hooks")
@@ -151,18 +179,20 @@ export async function executeArgv(argv, overrides = {}) {
         const session = new GraphSession({ delegated, application, transport: overrides.transport ?? fetchTransport });
         // A failing profile still reports its bounded read on stdout; the
         // nonzero exit travels through process state, never the payload.
-        const result = await runDoctor({ store: profiles, names, session });
+        const selected = names.length === 1 ? profiles.resolve(flags.profile) : undefined;
+        const result = await runDoctor({ store: profiles, names, session, selected });
         if (result.failed)
             process.exitCode = 1;
         return result.output;
     }
-    if (leaf.path === "login") {
+    if (leaf.path === "login" || leaf.path === "auth login" || leaf.path === "auth logout") {
         const selected = profiles.resolve(flags.profile);
         if (selected.profile.mode !== "delegated")
             throw new AxiError("Application profiles authenticate with client credentials; interactive login is unavailable", "VALIDATION_ERROR", ["mg-axi profile show --profile <name>", "Application tokens are acquired silently with the configured Graph .default audience"]);
         const { DelegatedAuth } = await import("./auth.js");
         const { MsalProvider } = await import("./msal-provider.js");
-        return { profile: selected.name, ...await new DelegatedAuth(new MsalProvider()).login(selected.profile, String(flags.method ?? "browser"), String(flags.scopes).split(",")) };
+        const service = overrides.delegated ?? new DelegatedAuth(new MsalProvider());
+        return { profile: selected.name, ...await (leaf.path === "auth logout" ? service.logout(selected.profile) : service.login(selected.profile, String(flags.method ?? "browser"), String(flags.scopes).split(","))) };
     }
     if (leaf.path === "entra conditional-access policy list" || leaf.path === "entra conditional-access policy show" || leaf.path === "entra conditional-access named-location list" || leaf.path === "entra conditional-access named-location show" || leaf.path === "entra conditional-access auth-strength-policy list" || leaf.path === "entra conditional-access auth-strength-policy show" || leaf.path === "entra conditional-access combination-configuration list" || leaf.path === "entra conditional-access combination-configuration show" || leaf.path === "entra conditional-access auth-method-mode list" || leaf.path === "entra conditional-access auth-method-mode show" || leaf.path === "entra conditional-access template list" || leaf.path === "entra conditional-access template show" || leaf.path === "entra conditional-access auth-context list" || leaf.path === "entra conditional-access auth-context show" || leaf.path === "entra conditional-access deleted-policy list" || leaf.path === "entra conditional-access deleted-policy show" || leaf.path === "entra conditional-access deleted-named-location list" || leaf.path === "entra conditional-access deleted-named-location show") {
         const selected = profiles.resolve(flags.profile);
@@ -1430,12 +1460,15 @@ export async function executeArgv(argv, overrides = {}) {
     throw new AxiError(`Command is not executable: ${operation?.disposition ?? "unavailable"} (${operation?.owningSlice ?? "no inventory mapping"})`, "NOT_IMPLEMENTED", [leafHelp(leaf)]);
 }
 export async function main() {
+    const stderrWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk, ...args) => stderrWrite(redactSecrets(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8")), ...args));
     await runAxiCli({
         description: DESCRIPTION,
         version: VERSION,
         topLevelHelp: TOP_LEVEL_HELP,
         // Strict resolution owns leaf help, so SDK help cannot bypass validation.
         argv: ["dispatch"],
+        stdout: { write: (value) => process.stdout.write(redactSecrets(value)) },
         home: () => localHome(),
         commands: {
             dispatch: async () => {
@@ -1445,7 +1478,7 @@ export async function main() {
             },
         },
         formatError: error => ({
-            output: `${encode(error instanceof AxiError ? { error: error.message, code: error.code, help: error.suggestions } : { error: "Unable to run mg-axi", help: ["mg-axi --help"] })}\n`,
+            output: `${redactSecrets(encode(error instanceof AxiError ? { error: error.message, code: error.code, help: error.suggestions } : { error: "Unable to run mg-axi", help: ["mg-axi --help"] }))}\n`,
             exitCode: error instanceof AxiError && error.code === "VALIDATION_ERROR" ? 2 : 1,
         }),
     });

package/dist/credentials.js

@@ -0,0 +1,78 @@
+import { rmSync } from "node:fs";
+import { AxiError } from "axi-sdk-js";
+import { statePath } from "./paths.js";
+import { PrivateFiles } from "./private-file.js";
+import { profileName } from "./profiles.js";
+import { registerCache } from "./redact.js";
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+// The only persistent credential backend. Access tokens never leave memory.
+export class Credentials {
+    path;
+    files;
+    constructor(path = statePath("credentials.json"), files = new PrivateFiles()) {
+        this.path = path;
+        this.files = files;
+    }
+    load(verifyAcl = false) {
+        let text;
+        try {
+            text = this.files.read(this.path, true, verifyAcl);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { version: 1, profiles: Object.create(null) };
+            throw error;
+        }
+        try {
+            const value = JSON.parse(text);
+            if (!object(value) || value.version !== 1 || !object(value.profiles) || Object.keys(value).some(key => !["version", "profiles"].includes(key)))
+                throw new Error("Invalid store");
+            for (const [name, entry] of Object.entries(value.profiles)) {
+                if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name) || !object(entry) || typeof entry.tenantId !== "string" || typeof entry.clientId !== "string" || typeof entry.cache !== "string" ||
+                    Object.keys(entry).some(key => !["tenantId", "clientId", "cache"].includes(key)) || !object(JSON.parse(entry.cache)))
+                    throw new Error("Invalid cache");
+            }
+            return value;
+        }
+        catch (error) {
+            if (error instanceof AxiError)
+                throw error;
+            throw new AxiError(`Invalid credential store ${this.path}`, "CONFIG_INVALID", ["Restore a valid protected credentials.json before signing in again"]);
+        }
+    }
+    name(profile) {
+        const name = profileName(profile);
+        if (!name)
+            throw new AxiError("Stored credentials require a named profile", "CONFIG_INVALID");
+        return name;
+    }
+    read(profile, verifyAcl = false) {
+        const records = this.load(verifyAcl).profiles;
+        const name = this.name(profile);
+        const entry = Object.hasOwn(records, name) ? records[name] : undefined;
+        if (!entry)
+            return undefined;
+        if (entry.tenantId.toLowerCase() !== profile.tenantId.toLowerCase() || entry.clientId.toLowerCase() !== profile.clientId.toLowerCase())
+            throw new AxiError("Stored credential binding does not match the selected tenant and client", "AUTH_REQUIRED", ["mg-axi auth login --profile <name> --scopes <comma-separated-Graph-scopes>"]);
+        return registerCache(entry.cache);
+    }
+    write(profile, serialized) {
+        registerCache(serialized);
+        const cache = JSON.parse(serialized);
+        delete cache.AccessToken;
+        const store = this.load();
+        Object.defineProperty(store.profiles, this.name(profile), { value: { tenantId: profile.tenantId, clientId: profile.clientId, cache: JSON.stringify(cache) }, enumerable: true, configurable: true, writable: true });
+        this.files.write(this.path, `${JSON.stringify(store, null, 2)}\n`);
+    }
+    remove(profile) {
+        const store = this.load();
+        const name = this.name(profile);
+        if (!Object.hasOwn(store.profiles, name))
+            return;
+        delete store.profiles[name];
+        if (Object.keys(store.profiles).length)
+            this.files.write(this.path, `${JSON.stringify(store, null, 2)}\n`);
+        else
+            rmSync(this.path);
+    }
+}

package/dist/docs.js

@@ -138,7 +138,7 @@ export function skillDescription() {
 // profile/login hints localHome() in cli.ts prepends to HOME_HELP; the
 // rest is HOME_HELP verbatim, so skill and home view cannot drift apart.
 export function skillHomeHints() {
-    return ["npx -y @knowttl/mg-axi profile list", "npx -y @knowttl/mg-axi login --help", ...HOME_HELP];
+    return ["npx -y @knowttl/mg-axi profile list", "npx -y @knowttl/mg-axi auth login --help", ...HOME_HELP];
 }
 // The full installable skill. Durable guidance only: read-only by default,
 // writes need preview plus typed confirmation, no secrets in output, the
@@ -165,13 +165,13 @@ export function skillDocument() {
         "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.",
@@ -194,19 +194,22 @@ export function skillDocument() {
         "",
         "## 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).",
+        "A client secret is weaker than a certificate or federated credential and needs scheduled rotation.",
         "",
         "Agent discovery has two install paths, and either suffices alone.",
         "For ambient context at every agent session start instead of the skill, install the CLI globally and opt into the session hook:",
@@ -224,18 +227,17 @@ export function skillDocument() {
         "## 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.",
-        "Secrets stay in protected storage references, never in argv, config files or output; credential fields carry expiry metadata only.",
+        "Secrets stay in credential references, never in argv, config files or output; credential fields carry expiry metadata only.",
         "Tests run offline with fixture credentials; never point tests at a real tenant.",
         "",
     ].join("\n");
@@ -404,7 +406,7 @@ export function capabilityDocument() {
         "",
         `- implemented read leaves: ${readCount} (${readLeaves.length} named Entra reads plus reviewed raw api get and doctor health check)`,
         `- implemented write leaves: ${writeLeaves.length} (named gated mutations below)`,
-        `- local leaves: ${localCount} (home, profile, login and setup views)`,
+        `- local leaves: ${localCount} (home, profile, config, auth, login alias and setup views)`,
         ...DISPOSITIONS.map(disposition => `- inventory ${disposition}: ${count(disposition)}`),
         "",
         ...auditRecord(rows),