@knowttl/mg-axi 0.1.3 → 0.1.6

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import { AxiError } from "axi-sdk-js";
 import { LEAVES, operationFor } from "./catalogue.js";
 import { listUsers } from "./entra-users.js";
+import { authStatus } from "./auth-status.js";
 // PACK-01: explicit release health check over the reviewed read-only session.
 // Doctor performs one documented bounded read per profile (entra user list
 // with a one-row window) and reports configuration, connectivity,
@@ -8,7 +9,7 @@ import { listUsers } from "./entra-users.js";
 // DelegatedAuth.credential and ApplicationAuth.credential never open a
 // browser or device-code flow, so doctor never signs in interactively.
 // Doctor never auto-installs, changes profiles or enables Graph writes;
-// silent token refresh may update the protected credential cache.
+// silent token refresh stays in memory.
 // See README.md for usage.
 export const DOCTOR_OPERATION = "GET:/users";
 export const DOCTOR_VERSION = "v1.0";
@@ -16,19 +17,18 @@ export const DOCTOR_CHECK = `entra user list --limit 1 (${DOCTOR_VERSION}:${DOCT
 export function doctorTargets(store, flag) {
     if (flag !== undefined)
         return [store.resolve(flag).name];
-    const items = store.list();
-    if (!items.length)
-        return [];
     try {
         return [store.resolve(undefined).name];
     }
-    catch {
-        return items.map(item => item.name);
+    catch (error) {
+        if (!(error instanceof AxiError) || !["PROFILE_REQUIRED", "PROFILE_AMBIGUOUS"].includes(error.code))
+            throw error;
+        return store.list().map(item => item.name);
     }
 }
 export async function runDoctor(args) {
     if (!args.names.length) {
-        throw new AxiError("No profiles are configured", "AUTH_REQUIRED", ["npx -y @knowttl/mg-axi profile create --help", "npx -y @knowttl/mg-axi setup"]);
+        throw new AxiError("No profiles are configured", "PROFILE_REQUIRED", ["npx -y @knowttl/mg-axi profile create --help", "npx -y @knowttl/mg-axi setup"]);
     }
     const leaf = LEAVES.find(item => item.path === "entra user list");
     const operation = leaf === undefined ? undefined : operationFor(leaf, DOCTOR_VERSION);
@@ -39,7 +39,9 @@ export async function runDoctor(args) {
     for (const name of args.names) {
         const rerun = `npx -y @knowttl/mg-axi doctor --profile ${name}`;
         try {
-            const selected = args.store.resolve(name);
+            args.store.verifyPermissions();
+            const selected = args.selected ?? args.store.resolve(name);
+            authStatus(name, selected.profile);
             // The same bounded read the named leaf serves: one fetched page, one
             // surfaced row, remainder buffered in a discarded cursor. Doctor keeps
             // no cursor and accepts none; recovery reruns doctor, not the read.

package/dist/graph-session.js

@@ -2,7 +2,9 @@ import { createHash, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { setTimeout as delay } from "node:timers/promises";
 import { AxiError } from "axi-sdk-js";
-import { validateApplicationProfile, validateDelegatedProfile, validateProfile, } from "./profiles.js";
+import { redactSecrets } from "./redact.js";
+import { PrivateFiles } from "./private-file.js";
+import { validateProfile, profileName } from "./profiles.js";
 // CORE-01: the single path that owns Graph URL construction, operation
 // authorization, credential attachment and response validation. Command
 // handlers call execute() with a catalogued inventory operation and bound
@@ -138,7 +140,7 @@ export function redactGraphValue(value) {
 }
 function redact(value) {
     if (typeof value === "string")
-        return SECRET_VALUE.some(pattern => pattern.test(value)) ? REDACTED : value;
+        return SECRET_VALUE.some(pattern => pattern.test(value)) ? REDACTED : redactSecrets(value);
     if (Array.isArray(value))
         return value.map(redact);
     if (value === null || typeof value !== "object")
@@ -617,8 +619,10 @@ function valuesOf(operation, body) {
 }
 export class GraphSession {
     deps;
-    constructor(deps) {
+    files;
+    constructor(deps, files = new PrivateFiles()) {
         this.deps = deps;
+        this.files = files;
     }
     cursorQuery(operation, cursor) {
         return decodeCursor(operation, cursor).query;
@@ -633,7 +637,7 @@ export class GraphSession {
                 "Use a route from inventory/operations.json; the session never builds uncatalogued URLs",
             ]);
         }
-        const profile = validateProfile(args.profile);
+        const profile = validateProfile(args.profile, this.files);
         this.authorizePolicy(profile, operation);
         const query = args.query ?? {};
         checkQueryContext(query, args.consistencyLevel);
@@ -645,8 +649,8 @@ export class GraphSession {
         let token;
         try {
             token = await beforeDeadline(async () => profile.mode === "delegated"
-                ? (await this.deps.delegated.credential(validateDelegatedProfile(profile), this.readScopes(args.scopes))).token
-                : (await this.deps.application.credential(validateApplicationProfile(profile), this.applicationScopes(args.scopes))).token, clock, deadline, signal);
+                ? (await this.deps.delegated.credential(profile, this.readScopes(args.scopes))).token
+                : (await this.deps.application.credential(profile, this.applicationScopes(args.scopes))).token, clock, deadline, signal);
         }
         catch (error) {
             signal?.throwIfAborted();
@@ -671,7 +675,7 @@ export class GraphSession {
                 "Use a route from inventory/operations.json; the session never builds uncatalogued URLs",
             ]);
         }
-        const profile = validateProfile(args.profile);
+        const profile = validateProfile(args.profile, this.files);
         this.authorizePolicy(profile, operation);
         checkLimit(args.limit);
         const budget = checkBudget(args.budget);
@@ -690,8 +694,8 @@ export class GraphSession {
         const signal = args.signal;
         const path = buildPath(operation.path, params);
         const context = createHash("sha256").update(JSON.stringify([
-            path, profile.mode, profile.tenantId.toLowerCase(), profile.clientId.toLowerCase(), profile.cloud,
-            profile.credentialRef, [...new Set(args.scopes ?? [])].sort(),
+            path, profileName(profile), profile.mode, profile.tenantId.toLowerCase(), profile.clientId.toLowerCase(), profile.cloud,
+            profile.mode === "delegated" ? profile.token : profile.auth === "certificate" ? [profile.privateKey, profile.thumbprintSha256] : profile.auth === "client-secret" ? profile.clientSecret : profile.token, [...new Set(args.scopes ?? [])].sort(),
         ])).digest("hex");
         if (resumed && resumed.context !== context)
             throw new AxiError("Collection cursor resource or authentication context does not match", "VALIDATION_ERROR", ["Resume under the original resource bindings, profile identity, credential reference and scopes"]);
@@ -733,8 +737,8 @@ export class GraphSession {
         let token;
         try {
             const credential = await beforeDeadline(async () => profile.mode === "delegated"
-                ? this.deps.delegated.credential(validateDelegatedProfile(profile), this.readScopes(args.scopes))
-                : this.deps.application.credential(validateApplicationProfile(profile), this.applicationScopes(args.scopes)), clock, deadline, signal);
+                ? this.deps.delegated.credential(profile, this.readScopes(args.scopes))
+                : this.deps.application.credential(profile, this.applicationScopes(args.scopes)), clock, deadline, signal);
             const acquiredIdentity = createHash("sha256").update(JSON.stringify([
                 profile.mode, credential.tenantId.toLowerCase(), credential.clientId.toLowerCase(),
                 profile.mode === "delegated" && "accountId" in credential ? credential.accountId : null,

package/dist/hook.js

@@ -1,37 +1,14 @@
 import { encode } from "@toon-format/toon";
 import { Profiles } from "./profiles.js";
-// Session-start ambient summary behind the mg-axi-hook entry point.
-// Local configuration state only: every configured profile name with its
-// tenant label, auth-cache presence and effective write posture, plus the
-// package version and one next-step hint. No session, transport, Graph or
-// sign-in call of any kind; every failure collapses to a short record with
-// exit code 0, so a missing or broken config never breaks agent startup.
-//
-// Auth-cache presence reads the OS credential store directly: delegated
-// profiles keep their MSAL session blob under the "mg-axi" service with the
-// session key below, so presence means a previous explicit login happened on
-// this machine. Only presence is reported; tokens and key material never
-// reach the output. Application profiles acquire tokens silently per run, so
-// they report the client-credentials mechanism instead of cache state.
-// Session cache key mirrors MsalProvider.application() in
-// src/msal-provider.ts; change both together.
-function delegatedSessionKey(profile) {
-    return JSON.stringify([profile.credentialRef.key, profile.tenantId, profile.clientId, profile.cloud]);
-}
-async function probeAuthPresence(profile) {
+import { Credentials } from "./credentials.js";
+import { PrivateFiles } from "./private-file.js";
+import { resolveSecret } from "./secrets.js";
+import { redactSecrets } from "./redact.js";
+async function probeAuthPresence(profile, files = new PrivateFiles()) {
     if (profile.mode !== "delegated")
         return "client-credentials";
-    let store;
-    try {
-        store = await import("keytar").then(module => module.default).catch(() => undefined);
-    }
-    catch {
-        return "unknown";
-    }
-    if (!store)
-        return "unknown";
     try {
-        return typeof await store.getPassword("mg-axi", delegatedSessionKey(profile)) === "string" ? "cached" : "sign-in required";
+        return ("stored" in profile.token ? new Credentials(undefined, files).read(profile) : resolveSecret(profile.token, files)) ? "cached" : "sign-in required";
     }
     catch {
         return "unknown";
@@ -44,17 +21,17 @@ const CONFIGURED_HINT = "Run npx -y @knowttl/mg-axi doctor --profile <name> to c
 const SETUP_HINT = "Run npx -y @knowttl/mg-axi setup to find the config path and example";
 export async function hookSummary(options) {
     try {
-        return await renderHookSummary(options);
+        return redactSecrets(await renderHookSummary(options));
     }
     catch {
         return "mg: status unavailable\n";
     }
 }
-async function renderHookSummary({ version, env = process.env, configPath, authPresence = probeAuthPresence }) {
+async function renderHookSummary({ version, env = process.env, configPath, files = new PrivateFiles(), authPresence = profile => probeAuthPresence(profile, files) }) {
     let store;
     let names;
     try {
-        store = new Profiles(configPath ?? env.MG_AXI_CONFIG);
+        store = new Profiles(configPath !== undefined && configPath.trim() !== "" ? configPath.trim() : env.MG_AXI_CONFIG !== undefined && env.MG_AXI_CONFIG.trim() !== "" ? env.MG_AXI_CONFIG.trim() : undefined, files);
         names = store.list().map(item => item.name);
     }
     catch {

package/dist/msal-app-provider.js

@@ -1,15 +1,24 @@
-import { 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.
+import { PrivateFiles } from "./private-file.js";
+import { resolveSecret } from "./secrets.js";
+import { registerSecret } from "./redact.js";
+// Application acquisition has no interactive or persistent credential fallback.
 export class MsalApplicationProvider {
+    files;
     storage = "session-only";
+    constructor(files = new PrivateFiles()) {
+        this.files = files;
+    }
     async acquire(profile, scopes) {
         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() }) },
+                ...(profile.auth === "client-secret"
+                    ? { clientSecret: resolveSecret(profile.clientSecret, this.files) }
+                    : profile.auth === "certificate"
+                        ? { clientCertificate: { thumbprintSha256: profile.thumbprintSha256, privateKey: this.privateKey(profile) } }
+                        : { clientAssertion: () => Promise.resolve(this.assertion(profile)) }) },
             system: { loggerOptions: { loggerCallback: () => { }, piiLoggingEnabled: false } },
         };
         const result = await new ConfidentialClientApplication(configuration)
@@ -18,25 +27,25 @@ export class MsalApplicationProvider {
             throw new Error("Empty application token response");
         if (result.authority.toLowerCase() !== `${configuration.auth.authority.toLowerCase()}/`)
             throw new Error("Configured application authority mismatch");
-        return { token: result.accessToken, expiresAt: result.expiresOn?.getTime() ?? NaN, tenantId: profile.tenantId, clientId: profile.clientId };
+        return { token: registerSecret(result.accessToken), expiresAt: result.expiresOn?.getTime() ?? NaN, tenantId: profile.tenantId, clientId: profile.clientId };
     }
-    async privateKey(key) {
-        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);
-        if (typeof material !== "string" || !material.trim())
-            throw new Error("Missing referenced certificate private key");
-        return material;
+    assertion(profile) {
+        if ("env" in profile.token && profile.token.env === "MG_AXI_TOKEN" && !process.env.MG_AXI_TOKEN?.trim()) {
+            const legacy = process.env.AZURE_FEDERATED_TOKEN_FILE?.trim();
+            if (legacy) {
+                process.stderr.write("AZURE_FEDERATED_TOKEN_FILE is deprecated; use MG_AXI_TOKEN instead\n");
+                if (!this.files.absolute(legacy))
+                    throw new AxiError("AZURE_FEDERATED_TOKEN_FILE must name an absolute file path", "CONFIG_INVALID", ["Set MG_AXI_TOKEN to the workload assertion"]);
+                return resolveSecret({ file: legacy }, this.files);
+            }
+        }
+        return resolveSecret(profile.token, this.files);
     }
-    async assertion() {
-        this.storage = "session-only";
-        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;
+    privateKey(profile) {
+        const material = resolveSecret(profile.privateKey, this.files);
+        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("Referenced privateKey is passphrase-protected; passphrase-protected keys are unsupported", "AUTH_REQUIRED", ["Provision an unencrypted PEM through the referenced environment variable or file"]);
+        return registerSecret(normalized);
     }
 }

package/dist/msal-provider.js

@@ -1,82 +1,95 @@
 import { PublicClientApplication } from "@azure/msal-node";
 import open from "open";
-// Only this adapter touches Microsoft authentication and OS credential storage.
+import { AxiError } from "axi-sdk-js";
+import { profileName } from "./profiles.js";
+import { Credentials } from "./credentials.js";
+import { resolveSecret } from "./secrets.js";
+import { redactSecrets, registerCache, registerSecret } from "./redact.js";
 export class MsalProvider {
-    storage = "session-only";
+    store;
+    storage = "protected-file";
     sessions = new Map();
-    async application(profile, fresh = false) {
-        const key = JSON.stringify([profile.credentialRef.key, profile.tenantId, profile.clientId, profile.cloud]);
+    constructor(store = new Credentials()) {
+        this.store = store;
+    }
+    key(profile) { return JSON.stringify([profileName(profile), profile.tenantId, profile.clientId, profile.cloud, profile.token]); }
+    application(profile, login = false) {
+        const key = this.key(profile);
+        this.storage = "stored" in profile.token ? "protected-file" : "session-only";
         const existing = this.sessions.get(key);
-        if (existing && !fresh) {
-            this.storage = existing.store ? "os-protected" : "session-only";
-            return existing.app;
-        }
-        const store = existing ? existing.store : await import("keytar").then(module => module.default).catch(() => undefined);
-        this.storage = store ? "os-protected" : "session-only";
-        if (fresh) {
-            this.sessions.delete(key);
-            if (store) {
-                await store.deletePassword("mg-axi", key);
-                if (await store.getPassword("mg-axi", key) !== null)
-                    throw new Error("Unable to wipe profile cache");
-            }
-        }
-        const configuration = {
+        if (existing && !login)
+            return existing;
+        let loaded = false;
+        let snapshot;
+        const app = new PublicClientApplication({
             auth: { clientId: profile.clientId, authority: `https://login.microsoftonline.com/${profile.tenantId}` },
             system: { loggerOptions: { loggerCallback: () => { }, piiLoggingEnabled: false } },
-        };
-        const app = new PublicClientApplication({
-            ...configuration,
-            cache: store ? { cachePlugin: {
+            cache: { cachePlugin: {
                     beforeCacheAccess: async (context) => {
-                        const saved = await store.getPassword("mg-axi", key);
-                        if (saved)
-                            context.tokenCache.deserialize(saved);
+                        if (!loaded) {
+                            snapshot = "stored" in profile.token ? this.store.read(profile) : resolveSecret(profile.token, this.store.files);
+                            loaded = true;
+                        }
+                        // MSAL overwrites its cache from the plugin snapshot before a silent lookup.
+                        if (snapshot)
+                            context.tokenCache.deserialize(registerCache(snapshot));
                     },
                     afterCacheAccess: async (context) => {
                         if (!context.cacheHasChanged)
                             return;
-                        const saved = context.tokenCache.serialize();
-                        if (process.platform === "win32" && Buffer.byteLength(saved, "utf8") > 2560) {
-                            await store.deletePassword("mg-axi", key);
-                            if (await store.getPassword("mg-axi", key) !== null)
-                                throw new Error("Unable to wipe profile cache");
-                            const session = new PublicClientApplication(configuration);
-                            session.getTokenCache().deserialize(saved);
-                            this.sessions.set(key, { app: session });
-                            this.storage = "session-only";
-                            return;
-                        }
-                        await store.setPassword("mg-axi", key, saved);
+                        snapshot = registerCache(context.tokenCache.serialize());
+                        // Hosted commands keep refreshed tokens only in memory. Explicit login owns persistence.
+                        if (login)
+                            this.store.write(profile, snapshot);
                     },
-                } } : undefined,
+                } },
         });
-        this.sessions.set(key, { app, store });
+        this.sessions.set(key, app);
         return app;
     }
     async login(profile, method, scopes) {
-        // Each explicit login starts with a new client and a verified empty protected cache.
-        const app = await this.application(profile, true);
-        const result = method === "browser"
-            ? await app.acquireTokenInteractive({ scopes, openBrowser: async (url) => { await open(url); }, prompt: "select_account", errorTemplate: "Sign-in failed. Return to mg-axi for recovery guidance." })
-            : await app.acquireTokenByDeviceCode({ scopes, deviceCodeCallback: response => {
-                    if (typeof response.userCode !== "string" || !response.userCode.trim() || typeof response.deviceCode !== "string" || !response.deviceCode.trim() || !Number.isFinite(response.expiresIn) || response.expiresIn <= 0)
-                        throw new Error("Invalid device-code challenge");
-                    // The one-time user challenge belongs only to explicit login stderr.
-                    process.stderr.write(`Open https://microsoft.com/devicelogin and enter ${response.userCode}\n`);
-                } });
-        return this.result(profile, result);
+        if (!("stored" in profile.token))
+            throw new AxiError("auth login requires token: {stored: true}", "CONFIG_INVALID");
+        this.sessions.delete(this.key(profile));
+        this.store.remove(profile);
+        const app = this.application(profile, true);
+        try {
+            const result = method === "browser"
+                ? await app.acquireTokenInteractive({ scopes, openBrowser: async (url) => { await open(url); }, prompt: "select_account", errorTemplate: "Sign-in failed. Return to mg-axi for recovery guidance." })
+                : await app.acquireTokenByDeviceCode({ scopes, deviceCodeCallback: response => {
+                        if (typeof response.userCode !== "string" || !response.userCode.trim() || typeof response.deviceCode !== "string" || !response.deviceCode.trim() || !Number.isFinite(response.expiresIn) || response.expiresIn <= 0)
+                            throw new Error("Invalid device-code challenge");
+                        process.stderr.write(redactSecrets(`Open https://microsoft.com/devicelogin and enter ${response.userCode}\n`));
+                    } });
+            const credential = this.result(profile, result);
+            // Subsequent silent acquisitions must not retain a persistence-enabled plugin.
+            this.sessions.delete(this.key(profile));
+            return credential;
+        }
+        catch (error) {
+            this.sessions.delete(this.key(profile));
+            this.store.remove(profile);
+            throw error;
+        }
     }
     async silent(profile, scopes) {
-        const app = await this.application(profile);
+        const app = this.application(profile);
         const accounts = (await app.getTokenCache().getAllAccounts()).filter(account => account.tenantId.toLowerCase() === profile.tenantId.toLowerCase());
         if (accounts.length !== 1)
             throw new Error("Explicit login required");
-        return this.result(profile, await app.acquireTokenSilent({ scopes, account: accounts[0] }));
+        const credential = this.result(profile, await app.acquireTokenSilent({ scopes, account: accounts[0] }));
+        if (credential.accountId !== accounts[0].homeAccountId)
+            throw new Error("Configured account mismatch");
+        return credential;
+    }
+    async logout(profile) {
+        this.sessions.delete(this.key(profile));
+        if ("stored" in profile.token)
+            this.store.remove(profile);
     }
     result(profile, result) {
         if (!result?.account || result.tenantId.toLowerCase() !== profile.tenantId.toLowerCase())
             throw new Error("Configured tenant mismatch");
-        return { token: result.accessToken, expiresAt: result.expiresOn?.getTime() ?? NaN, tenantId: result.tenantId, clientId: profile.clientId, accountId: result.account.homeAccountId };
+        return { token: registerSecret(result.accessToken), expiresAt: result.expiresOn?.getTime() ?? NaN, tenantId: result.tenantId, clientId: profile.clientId, accountId: result.account.homeAccountId };
     }
 }

package/dist/mutations.js

@@ -1,10 +1,12 @@
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, openSync, unlinkSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { AxiError } from "axi-sdk-js";
 import { encodeGraphPathSegment, GRAPH_HOST, redactGraphValue } from "./graph-session.js";
-import { validateApplicationProfile, validateDelegatedProfile } from "./profiles.js";
+import { booleanEnv, movedError, validateApplicationProfile, validateDelegatedProfile } from "./profiles.js";
+import { statePath } from "./paths.js";
+import { PrivateFiles } from "./private-file.js";
 // Shared mutation coordinator for reviewed named mutation families.
 // The gate order follows az-axi's write gates as the reference: read-only default,
 // allowWrites plus a scope allowlist, preview, --execute, --confirm,
@@ -15,15 +17,19 @@ import { validateApplicationProfile, validateDelegatedProfile } from "./profiles
 export const READ_ONLY_ENV = "MG_AXI_READ_ONLY";
 export const WRITE_LOG_ENV = "MG_AXI_WRITE_LOG";
 export function readOnlyForced(env = process.env) {
-    return env[READ_ONLY_ENV] === "1";
+    return booleanEnv(READ_ONLY_ENV, env);
 }
 // Mutation intents and outcomes are journaled here: MG_AXI_WRITE_LOG when
-// set, otherwise ~/.mg-axi/writes.log. A blank override falls back.
+// set, otherwise the machine-local state directory. A blank override falls back.
 export function resolveWriteLogPath(env = process.env) {
     const override = env[WRITE_LOG_ENV]?.trim();
     if (override)
         return override;
-    return join(homedir(), ".mg-axi", "writes.log");
+    const target = statePath("writes.log", env);
+    const legacy = join(homedir(), ".mg-axi", "writes.log");
+    if (!existsSync(target) && existsSync(legacy))
+        movedError("Write log", legacy, target, "The moved journal keeps its intent and outcome history");
+    return target;
 }
 export const mutationFetchTransport = async (request) => {
     const response = await fetch(request.url, {
@@ -155,8 +161,8 @@ function decodeMutationBody(response) {
 // send needs a coordinator authorization minted after the write gates pass.
 // The bound profile copy is private; no profile snapshot is exposed.
 export function createMutationSender(args) {
-    const { delegated, application, transport } = args;
-    const bound = args.profile.mode === "application" ? validateApplicationProfile(args.profile) : validateDelegatedProfile(args.profile);
+    const { delegated, application, transport, files = new PrivateFiles() } = args;
+    const bound = args.profile.mode === "application" ? validateApplicationProfile(args.profile, files) : validateDelegatedProfile(args.profile, files);
     async function credential(scopes, signal) {
         signal?.throwIfAborted();
         if (bound.mode === "delegated") {
@@ -165,14 +171,14 @@ export function createMutationSender(args) {
                     "Pass the operation's documented delegated permission using full https://graph.microsoft.com/ scope names",
                 ]);
             }
-            return (await delegated.credential(validateDelegatedProfile(bound), scopes)).token;
+            return (await delegated.credential(bound, scopes)).token;
         }
         if (scopes !== undefined) {
             throw new AxiError("Application profiles use the configured Graph .default audience; delegated scopes are unavailable", "VALIDATION_ERROR", [
                 "mg-axi profile show --profile <name>",
             ]);
         }
-        return (await application.credential(validateApplicationProfile(bound))).token;
+        return (await application.credential(bound)).token;
     }
     async function send(authorization, options) {
         let handedOff = false;
@@ -240,8 +246,8 @@ export function createMutationSender(args) {
     return sender;
 }
 function flushDirectory(path) {
-    // Node cannot open directory handles on Windows; journal fsync still
-    // applies, and recordAudit pre-creates the journal file there instead.
+    // Node cannot open directory handles on Windows; atomic journal writes
+    // still fsync the file before replacement.
     if (process.platform === "win32")
         return;
     const fd = openSync(path, "r");
@@ -266,16 +272,16 @@ function serialize(value) {
     }
 }
 export function createMutationCoordinator(args) {
-    const { profile, delegated, application, transport } = args;
+    const { profile, delegated, application, transport, files = new PrivateFiles() } = args;
     const clock = args.clock ?? Date.now;
     const journalPath = args.journalPath ?? resolveWriteLogPath();
-    const validated = profile.mode === "application" ? validateApplicationProfile(profile) : validateDelegatedProfile(profile);
+    const validated = profile.mode === "application" ? validateApplicationProfile(profile, files) : validateDelegatedProfile(profile, files);
     const scope = Object.freeze({
         tenantId: validated.tenantId,
         allowWrites: validated.writes?.allowWrites === true,
         operations: Object.freeze([...(validated.writes?.operations ?? [])]),
     });
-    const sender = createMutationSender({ profile: validated, delegated, application, transport });
+    const sender = createMutationSender({ profile: validated, delegated, application, transport, files });
     function enforceWriteGates(definition) {
         // Gate 1: forced read-only overrides every profile.
         // Gate 2: the profile must opt in through hand-edited configuration.
@@ -357,7 +363,7 @@ export function createMutationCoordinator(args) {
         const line = JSON.stringify({ ...safe, intentKey: record.intentKey });
         try {
             const directory = dirname(journalPath);
-            const firstCreated = mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const firstCreated = files.directory(directory);
             if (firstCreated) {
                 let path = directory;
                 const parent = dirname(firstCreated);
@@ -367,48 +373,31 @@ export function createMutationCoordinator(args) {
                 }
                 flushDirectory(parent);
             }
-            if (process.platform === "win32" && !existsSync(journalPath)) {
-                const journal = openSync(journalPath, "a", 0o600);
-                try {
-                    fsyncSync(journal);
-                }
-                finally {
-                    closeSync(journal);
-                }
-            }
             const lockPath = `${journalPath}.lock`;
             const lock = openSync(lockPath, "wx", 0o600);
             try {
-                const created = !existsSync(journalPath);
-                const journal = openSync(journalPath, "a+", 0o600);
-                try {
-                    if (record.kind === "intent") {
-                        const contents = readFileSync(journal, "utf8");
-                        if (contents && !contents.endsWith("\n"))
-                            throw new Error("Incomplete mutation journal");
-                        const records = contents.split("\n").filter(Boolean)
-                            .map(entry => JSON.parse(entry));
-                        if (records.some(entry => !entry || !["intent", "outcome"].includes(entry.kind)
-                            || typeof entry.intentKey !== "string" || !/^[a-f0-9]{64}$/.test(entry.intentKey))) {
-                            throw new Error("Invalid mutation journal");
-                        }
-                        // No automatic replay: a recreated coordinator refuses an intent
-                        // recorded without a terminal outcome, and a duplicate intent id
-                        // is never reserved twice.
-                        if (records.some(entry => entry.kind === "intent" && entry.intentKey === record.intentKey)) {
-                            throw new AxiError(`blocked: intent '${record.id}' was already reserved`, "ALREADY_EXECUTED", [
-                                `Intent '${record.id}' requires manual reconciliation; read back its target and never resend it`,
-                            ]);
-                        }
+                files.protect(lockPath);
+                const contents = existsSync(journalPath) ? files.read(journalPath) : "";
+                if (record.kind === "intent") {
+                    if (contents && !contents.endsWith("\n"))
+                        throw new Error("Incomplete mutation journal");
+                    const records = contents.split("\n").filter(Boolean)
+                        .map(entry => JSON.parse(entry));
+                    if (records.some(entry => !entry || !["intent", "outcome"].includes(entry.kind)
+                        || typeof entry.intentKey !== "string" || !/^[a-f0-9]{64}$/.test(entry.intentKey))) {
+                        throw new Error("Invalid mutation journal");
+                    }
+                    // No automatic replay: a recreated coordinator refuses an intent
+                    // recorded without a terminal outcome, and a duplicate intent id
+                    // is never reserved twice.
+                    if (records.some(entry => entry.kind === "intent" && entry.intentKey === record.intentKey)) {
+                        throw new AxiError(`blocked: intent '${record.id}' was already reserved`, "ALREADY_EXECUTED", [
+                            `Intent '${record.id}' requires manual reconciliation; read back its target and never resend it`,
+                        ]);
                     }
-                    writeFileSync(journal, `${line}\n`);
-                    fsyncSync(journal);
-                    if (created)
-                        flushDirectory(directory);
-                }
-                finally {
-                    closeSync(journal);
                 }
+                files.write(journalPath, `${contents}${line}\n`);
+                flushDirectory(directory);
             }
             finally {
                 closeSync(lock);
@@ -416,7 +405,7 @@ export function createMutationCoordinator(args) {
             }
         }
         catch (error) {
-            if (error instanceof AxiError && error.code === "ALREADY_EXECUTED")
+            if (error instanceof AxiError && (error.code === "ALREADY_EXECUTED" || error.code === "CONFIG_INSECURE"))
                 throw error;
             if (record.kind === "intent") {
                 throw new AxiError(`Mutation intent '${record.id}' could not be recorded`, "INTENT_NOT_RECORDED", [

package/dist/paths.js

@@ -0,0 +1,17 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, win32 } from "node:path";
+export function toolDirectory(kind, env = process.env, platform = process.platform, home = homedir()) {
+    if (platform === "win32") {
+        const base = env[kind === "config" ? "APPDATA" : "LOCALAPPDATA"];
+        return win32.join(base || win32.join(home, "AppData", kind === "config" ? "Roaming" : "Local"), "mg-axi");
+    }
+    const base = env[kind === "config" ? "XDG_CONFIG_HOME" : "XDG_STATE_HOME"];
+    return join(base && isAbsolute(base) ? base : join(home, kind === "config" ? ".config" : ".local/state"), "mg-axi");
+}
+export function configPath(env = process.env) {
+    const override = env.MG_AXI_CONFIG?.trim();
+    return override ? override : join(toolDirectory("config", env), "config.json");
+}
+export function statePath(name, env = process.env) {
+    return join(toolDirectory("state", env), name);
+}