@knowttl/mg-axi 0.1.4 → 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);
@@ -30,7 +34,7 @@ export class ApplicationAuth {
         catch (error) {
             // Provider AUTH_REQUIRED failures already name only the credential
             // reference, never its value; everything else stays fully generic.
-            if (error instanceof AxiError && error.code === "AUTH_REQUIRED")
+            if (error instanceof AxiError && ["AUTH_REQUIRED", "CONFIG_INVALID", "CONFIG_INSECURE"].includes(error.code))
                 throw error;
             throw this.failure();
         }
@@ -41,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,23 +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 referenced storage" },
-            "certificate-key-file": { value: "path", description: "Application only: certificate PEM private key from this 0600 file; omit both key flags for the OS keychain" },
-            "certificate-key-env": { value: "env-var-name", description: "Application only: certificate PEM private key from this environment variable; omit both key flags for the OS keychain" },
+            "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: "path", description: "Application only: client secret from this 0600 file; exactly one of this or --client-secret-env" },
-            federated: { description: "Application only: workload federation via the assertion file named by --federated-token-file-env" },
-            "federated-token-file-env": { value: "env-var-name", description: "Application only: environment variable naming the workload assertion file; defaults to AZURE_FEDERATED_TOKEN_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 <40-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"] },
+            "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: {
@@ -2790,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,
@@ -2828,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,23 +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") {
-        const credentialFlags = ["certificate-thumbprint", "client-secret-env", "client-secret-file", "certificate-key-file", "certificate-key-env", "federated-token-file-env"];
+        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: optional("certificate-thumbprint"), federated: !!flags.federated, clientSecretEnv: optional("client-secret-env"), clientSecretFile: optional("client-secret-file"), certificateKeyFile: optional("certificate-key-file"), certificateKeyEnv: optional("certificate-key-env"), federatedTokenFileEnv: optional("federated-token-file-env") }
+            ? { 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")
@@ -153,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);
@@ -1432,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 () => {
@@ -1447,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,18 +194,18 @@ 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).",
@@ -227,14 +227,13 @@ 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.",
@@ -407,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),