@knowttl/mg-axi 0.1.3 → 0.1.4

package/README.md

@@ -1256,19 +1256,38 @@ mg-axi profile create --name batch --tenant <tenant-id> --client <client-id> --c
 mg-axi profile show --profile daemon
 ```
 
-Omitting `--mode` selects delegated mode; certificate and federation flags require application mode.
+Omitting `--mode` selects delegated mode; certificate, client-secret and federation flags require application mode.
 Application profiles reject `--allow-device-code`, and `login` with either login method exits 2 before authentication.
 For certificates, register the matching public certificate on the app registration.
-The provider expects a PEM private key in the OS credential store under service `mg-axi` and account equal to the profile's `credentialRef.key`, shown by `profile show`.
+By default the provider expects a PEM private key in the OS credential store under service `mg-axi` and account equal to the profile's `credentialRef.key`, shown by `profile show`.
 Profile creation records the thumbprint and reference; it does not import the private key, and there is no CLI key-import command.
 Provision that key through protected storage tooling; never put private keys in argv or profile JSON.
-Certificate acquisition fails if `keytar` or the referenced key is unavailable; there is no plaintext or session-only key fallback.
+Keychain certificate acquisition fails if `keytar` or the referenced key is unavailable; file and environment key holders below authenticate session-only instead.
 For workload federation, configure the app registration's federated credential mapping for the workload and set `AZURE_FEDERATED_TOKEN_FILE` to its assertion file.
 The provider reads the file on each assertion request so projected tokens can rotate; missing or empty assertions fail authentication.
+`--federated-token-file-env <NAME>` names a different holder variable when the workload does not use the default.
+
+Headless systems (containers, CI, services) have no OS keychain, so application profiles also accept file and environment references that are read at acquisition time:
+
+```sh
+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 --name daemon-file --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 daemon-env --tenant <tenant-id> --client <client-id> --cloud commercial --mode application --certificate-thumbprint <40-hex-digit-thumbprint> --certificate-key-env MG_AXI_PRIVATE_KEY
+MG_AXI_CLIENT_SECRET=<secret> mg-axi doctor --profile svc
+```
+
+A profile stores only the reference (an env var name or a file path), never the value.
+The environment supplies the value on each acquisition, so rotation updates the env var or file contents with no profile change.
+Relative paths resolve against the working directory at acquisition time.
+Key and secret files must be regular files owned by the current user with mode 0600, never symlinks; Windows skips the ownership and mode checks.
+A missing, empty or exposed holder fails closed with `AUTH_REQUIRED` naming only the reference, never its value.
+PEM values from env vars may use escaped `\n` newlines; passphrase-protected keys are unsupported.
+A client secret is weaker than a certificate or federated credential: it is a bearer string with no proof of possession.
+Prefer certificates or federation where the platform allows them, and rotate secrets on a schedule.
 Application credentials remain in process memory and are reacquired at a 60-second expiry margin.
 The service requests only `https://graph.microsoft.com/.default`, representing the app registration's admin-consented Graph application permissions, with no signed-in user.
 Ask an administrator to grant those permissions on the configured app registration; per-command delegated scopes cannot narrow the application token.
-Acquisition failures return `AUTH_REQUIRED` with consent and certificate/federation guidance, without user or device-code fallback.
+Acquisition failures return `AUTH_REQUIRED` with consent and credential-holder guidance, without user or device-code fallback.
 
 Run `corepack pnpm build`, `corepack pnpm test` (test files run at most 4 at a time via `--test-concurrency=4` in the `test` script) and `corepack pnpm lint` for shell validation.
 The [implementation plan](PLAN.md) remains the design authority.

package/dist/app-auth.js

@@ -27,7 +27,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 && error.code === "AUTH_REQUIRED")
+                throw error;
             throw this.failure();
         }
     }

package/dist/catalogue.js

@@ -506,9 +506,14 @@ 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": { 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" },
+            "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"] },
     { 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,

package/dist/cli.js

@@ -118,10 +118,12 @@ export async function executeArgv(argv, overrides = {}) {
         return localHome(flags.profile);
     const profiles = new Profiles();
     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", "client-secret-env", "client-secret-file", "certificate-key-file", "certificate-key-env", "federated-token-file-env"];
+        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"), 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") }
             : undefined);
     }
     if (leaf.path === "profile list") {

package/dist/docs.js

@@ -207,6 +207,9 @@ export function skillDocument() {
         "",
         "Configuration defaults to `~/.mg-axi/config.json`; `MG_AXI_CONFIG` selects a separate file.",
         "`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:",
@@ -235,7 +238,7 @@ export function skillDocument() {
         "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");

package/dist/msal-app-provider.js

@@ -1,15 +1,19 @@
-import { readFileSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
 import { ConfidentialClientApplication } from "@azure/msal-node";
+import { AxiError } from "axi-sdk-js";
 import { graphAudience } from "./app-auth.js";
 // Only this adapter touches application credentials; keys and assertions are referenced, never logged.
 export class MsalApplicationProvider {
     storage = "session-only";
     async acquire(profile, scopes) {
+        const ref = profile.credentialRef;
         const configuration = {
             auth: { clientId: profile.clientId, authority: `https://login.microsoftonline.com/${profile.tenantId}`,
-                ...(profile.credentialRef.provider === "certificate"
-                    ? { clientCertificate: { thumbprint: profile.credentialRef.thumbprint, privateKey: await this.privateKey(profile.credentialRef.key) } }
-                    : { clientAssertion: () => this.assertion() }) },
+                ...(ref.provider === "client-secret"
+                    ? { clientSecret: this.clientSecret(ref) }
+                    : ref.provider === "certificate"
+                        ? { clientCertificate: { thumbprint: ref.thumbprint, privateKey: await this.privateKey(ref) } }
+                        : { clientAssertion: () => this.assertion(ref) }) },
             system: { loggerOptions: { loggerCallback: () => { }, piiLoggingEnabled: false } },
         };
         const result = await new ConfidentialClientApplication(configuration)
@@ -20,23 +24,102 @@ export class MsalApplicationProvider {
             throw new Error("Configured application authority mismatch");
         return { token: result.accessToken, expiresAt: result.expiresOn?.getTime() ?? NaN, tenantId: profile.tenantId, clientId: profile.clientId };
     }
-    async privateKey(key) {
+    async privateKey(ref) {
+        if (ref.keyFile !== undefined) {
+            this.storage = "session-only";
+            return this.normalizeKey(this.readProtectedFile(ref.keyFile), ref.keyFile);
+        }
+        if (ref.keyEnv !== undefined) {
+            this.storage = "session-only";
+            const material = process.env[ref.keyEnv];
+            if (typeof material !== "string" || !material.trim())
+                throw this.missing(ref.keyEnv);
+            return this.normalizeKey(material, ref.keyEnv);
+        }
         const store = await import("keytar").then(module => module.default).catch(() => undefined);
         this.storage = store ? "os-protected" : "session-only";
-        const material = await store?.getPassword("mg-axi", key).catch(() => null);
+        const material = await store?.getPassword("mg-axi", ref.key).catch(() => null);
         if (typeof material !== "string" || !material.trim())
             throw new Error("Missing referenced certificate private key");
         return material;
     }
-    async assertion() {
+    clientSecret(ref) {
         this.storage = "session-only";
-        const file = process.env.AZURE_FEDERATED_TOKEN_FILE;
+        if (ref.secretEnv !== undefined) {
+            const secret = process.env[ref.secretEnv];
+            if (typeof secret !== "string" || !secret.trim())
+                throw this.missing(ref.secretEnv);
+            return secret.trim();
+        }
+        if (ref.secretFile !== undefined)
+            return this.readProtectedFile(ref.secretFile);
+        throw new Error("Missing client-secret credential holder");
+    }
+    async assertion(ref) {
+        this.storage = "session-only";
+        if (ref.tokenFileEnv === undefined) {
+            const file = process.env.AZURE_FEDERATED_TOKEN_FILE;
+            if (!file?.trim())
+                throw new Error("Missing federated token source");
+            // Read on every invocation: projected federated tokens rotate on disk.
+            const assertion = readFileSync(file, "utf8").trim();
+            if (!assertion)
+                throw new Error("Missing federated token source");
+            return assertion;
+        }
+        const file = process.env[ref.tokenFileEnv];
         if (!file?.trim())
-            throw new Error("Missing federated token source");
+            throw this.missing(ref.tokenFileEnv);
         // Read on every invocation: projected federated tokens rotate on disk.
-        const assertion = readFileSync(file, "utf8").trim();
-        if (!assertion)
-            throw new Error("Missing federated token source");
-        return assertion;
+        try {
+            const assertion = readFileSync(file, "utf8").trim();
+            if (!assertion)
+                throw this.missing(ref.tokenFileEnv);
+            return assertion;
+        }
+        catch (error) {
+            if (error instanceof AxiError)
+                throw error;
+            throw this.missing(ref.tokenFileEnv);
+        }
+    }
+    // Key and secret files hold long-lived material: regular file, owned by the
+    // current user, mode 0600, never a symlink. Relative paths resolve against
+    // the process working directory at acquire time. Windows skips the
+    // ownership and mode checks. Every failure names only the path, never content.
+    readProtectedFile(path) {
+        try {
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink() || !stat.isFile())
+                throw this.missing(path);
+            if (process.platform !== "win32") {
+                if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+                    throw this.missing(path);
+                if ((stat.mode & 0o777) !== 0o600)
+                    throw this.missing(path);
+            }
+            const content = readFileSync(path, "utf8").trim();
+            if (!content)
+                throw this.missing(path);
+            return content;
+        }
+        catch (error) {
+            if (error instanceof AxiError)
+                throw error;
+            throw this.missing(path);
+        }
+    }
+    // PEM material from files and env vars; env vars may carry escaped "\n".
+    normalizeKey(material, reference) {
+        const normalized = material.includes("\n") ? material : material.replace(/\\n/g, "\n");
+        if (/ENCRYPTED PRIVATE KEY/.test(normalized) || /Proc-Type:\s*4,ENCRYPTED/.test(normalized))
+            throw new AxiError(`Application credential reference ${reference} is passphrase-protected; passphrase-protected keys are unsupported`, "AUTH_REQUIRED", ["mg-axi profile show --profile <name>", "Provision an unencrypted PEM through the referenced environment variable or file"]);
+        if (!normalized.trim())
+            throw this.missing(reference);
+        return normalized;
+    }
+    // Fail-closed holder error: names only the env var name or file path.
+    missing(reference) {
+        return new AxiError(`Application credential unavailable for the configured reference ${reference}; no user or device-code fallback was attempted`, "AUTH_REQUIRED", ["mg-axi profile show --profile <name>", "Supply the referenced credential through the named environment variable or file"]);
     }
 }

package/dist/profiles.js

@@ -11,6 +11,9 @@ 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"]);
 }
 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;
@@ -47,18 +50,35 @@ export function validateApplicationProfile(value) {
     const ref = profile.credentialRef;
     const writes = validateWrites(value.writes);
     const writeFields = writes === undefined ? {} : { writes };
-    if (ref.provider === "certificate" && exact(ref, ["provider", "key", "thumbprint"]) && typeof ref.key === "string" && guid.test(ref.key) &&
-        typeof ref.thumbprint === "string" && thumbprint.test(ref.thumbprint)) {
+    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 });
     }
-    if (ref.provider === "federated" && exact(ref, ["provider", "key"]) && typeof ref.key === "string" && guid.test(ref.key)) {
+    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: "federated", key: ref.key }), ...writeFields });
+            credentialRef: Object.freeze({ provider: "certificate", key: ref.key, thumbprint: ref.thumbprint.toLowerCase(), ...keySource }), ...writeFields });
     }
-    invalid("Invalid application profile; credentialRef must be a certificate or federated reference, never inlined key material");
+    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 });
+    }
+    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 });
+    }
+    invalid("Invalid application profile; credentialRef must be a certificate, client-secret or federated reference, never inlined key material");
 }
 export function validateProfile(value) {
     if (!!value && typeof value === "object" && !Array.isArray(value) && value.mode === "application")
@@ -107,15 +127,41 @@ export class Profiles {
             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 protected storage");
-        if (application && ((certificate === undefined) === !federated))
-            invalid("Application profiles use exactly one credential: --certificate-thumbprint or --federated");
+            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`);
+        }
+        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: certificate === undefined ? { provider: "federated", key: randomUUID() } : { provider: "certificate", key: randomUUID(), thumbprint: certificate }, allowDeviceCode: false })
+                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))

package/dist/setup.js

@@ -105,7 +105,7 @@ 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; secrets stay in protected storage references, never in argv or config`,
+            `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`,
             "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 doctor",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/mg-axi",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Agent-facing Microsoft Graph CLI, read-only by default",
   "type": "module",
   "bin": {

package/skills/mg-axi/SKILL.md

@@ -346,6 +346,9 @@ 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.
 `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:
@@ -374,5 +377,5 @@ Reads run through a session that authorizes only catalogued operations before si
 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.