@knowttl/mg-axi 0.1.2 → 0.1.4

package/dist/entra-terms-of-use.js

@@ -1,4 +1,5 @@
 import { AxiError } from "axi-sdk-js";
+import { listTotals } from "./list-totals.js";
 // EXT-01 terms-of-use subfamily: the read mapping behind
 // `mg-axi entra agreement list/show`,
 // `mg-axi entra agreement acceptance list/show --agreement <agreement-id>`
@@ -264,20 +265,22 @@ export async function listAgreements(session, flags, profile, operation, help, p
     if (!result.complete) {
         return {
             agreements,
-            count: { returned: agreements.length, complete: false, reason: result.reason },
+            ...listTotals(agreements.length, result.total, "agreements", false),
+            complete: false,
+            reason: result.reason,
             cursor: result.cursor,
             help: [...truncationHints, resumeHint(profileName), showHint],
         };
     }
-    const count = { returned: agreements.length, complete: true };
     if (!agreements.length) {
         return {
             agreements,
-            count,
+            ...listTotals(agreements.length, result.total, "agreements", true),
+            complete: true,
             help: ["0 agreements matched; no terms-of-use agreements are configured for the tenant, or no row passed --filter"],
         };
     }
-    return { agreements, count, help: [...truncationHints, showHint] };
+    return { agreements, ...listTotals(agreements.length, result.total, "agreements", true), complete: true, help: [...truncationHints, showHint] };
 }
 export async function showAgreement(session, flags, profile, operation, help, profileName) {
     const { select, fields } = selectedFields(flags, KNOWN_AGREEMENTS, KNOWN_AGREEMENT_FIELDS, DEFAULT_AGREEMENT_SHOW_SELECT, help, "agreement");
@@ -325,20 +328,22 @@ async function collectAcceptances(session, flags, profile, operation, help, prof
     if (!result.complete) {
         return {
             agreementAcceptances: acceptances,
-            count: { returned: acceptances.length, complete: false, reason: result.reason },
+            ...listTotals(acceptances.length, result.total, "agreement acceptances", false),
+            complete: false,
+            reason: result.reason,
             cursor: result.cursor,
             help: [...truncationHints, resumeHint(profileName), showHint],
         };
     }
-    const count = { returned: acceptances.length, complete: true };
     if (!acceptances.length) {
         return {
             agreementAcceptances: acceptances,
-            count,
+            ...listTotals(acceptances.length, result.total, "agreement acceptances", true),
+            complete: true,
             help: ["0 agreement acceptances matched; nobody recorded an acceptance in scope yet, or no row passed --filter"],
         };
     }
-    return { agreementAcceptances: acceptances, count, help: [...truncationHints, showHint] };
+    return { agreementAcceptances: acceptances, ...listTotals(acceptances.length, result.total, "agreement acceptances", true), complete: true, help: [...truncationHints, showHint] };
 }
 async function showAcceptanceById(session, flags, profile, operation, help, profileName, command, agreement) {
     const { select, fields } = selectedFields(flags, KNOWN_ACCEPTANCES, KNOWN_ACCEPTANCE_FIELDS, DEFAULT_ACCEPTANCE_SELECT, help, "agreement-acceptance");

package/dist/graph-session.js

@@ -25,6 +25,7 @@ const READ_SCOPES = new Set([
     "AdministrativeUnit.Read.All",
     "Application.Read.All",
     "AuditLog.Read.All",
+    "AuthenticationContext.Read.All",
     "CustomSecAttributeDefinition.Read.All",
     "CrossTenantInformation.ReadBasic.All",
     "DelegatedAdminRelationship.Read.All",

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

@@ -15,7 +15,9 @@ const READ_FAMILY_PREFIXES = [
     ["entra user", "user"],
     ["entra registration", "registration"],
     ["entra group", "group"],
+    ["entra directory-role-template", "directory-role/PIM"],
     ["entra directory-role", "directory-role/PIM"],
+    ["entra scoped-role-membership", "directory-role/PIM"],
     ["entra role-assignment", "directory-role/PIM"],
     ["entra pim", "directory-role/PIM"],
     ["entra device", "device"],
@@ -49,6 +51,7 @@ const READ_FAMILY_PREFIXES = [
     ["entra tenant-information", "tenant information"],
     ["entra sign-in", "sign-in/directory-audit"],
     ["entra directory-audit", "sign-in/directory-audit"],
+    ["entra provisioning", "sign-in/directory-audit"],
     ["entra application", "application/service-principal and consent grants"],
     ["entra service-principal", "application/service-principal and consent grants"],
     ["entra risky-user", "risk"],
@@ -102,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",
@@ -112,7 +115,7 @@ export function setupView(store) {
             reads,
             writes,
             local: implemented.length - reads - writes,
-            api: `Entra ${families.slice(0, -1).join(", ")} and ${families.at(-1)} reads plus reviewed raw api get, one gated group-membership write, one gated account enable/disable write, one gated session-revocation write and one gated risky-user dismissal write; every other operation is scheduled, blocked, deprecated or excluded`,
+            api: `Entra ${families.slice(0, -1).join(", ")} and ${families.at(-1)} reads plus reviewed raw api get, one gated group-membership write, one gated account enable/disable write, one gated session-revocation write and one gated risky-user dismissal write; every other v1.0 operation is deferred out of v1, and every other beta operation remains scheduled (never agreed for v1), blocked, deprecated, unavailable or excluded`,
             report: "docs/coverage.md",
         },
         integration: "Install skills/mg-axi/SKILL.md explicitly through your agent's skill installation mechanism; setup only shows guidance and installs no skills or hooks",