@knowttl/mg-axi 0.1.0

package/dist/entra-ca-policy-update.js

@@ -0,0 +1,353 @@
+import { AxiError } from "axi-sdk-js";
+import { encodeGraphPathSegment, redactGraphValue, REDACTED } from "./graph-session.js";
+// WRITE-04 usage, reviewed fields, permissions and lockout requirements are
+// owned by README.md; shared execution gates are owned by docs/execution.md.
+// Reviewed against v1.0 conditionalaccesspolicy-update on REVIEWED_ON:
+// Graph documents no ETag or If-Match precondition, so fresh reads cannot
+// make the PATCH atomic. Its 204 response contains no policy body; the
+// coordinator records the outcome, and callers must verify with policy show.
+export const REVIEWED_ON = "2026-10-04";
+// Scope name a profile hand-enables in its writes.operations allowlist.
+export const CA_POLICY_UPDATE_OPERATION = "entra.conditional-access.policy.update";
+export const CA_POLICY_UPDATE_SCOPES = [
+    "https://graph.microsoft.com/Policy.Read.All",
+    "https://graph.microsoft.com/Policy.ReadWrite.ConditionalAccess",
+];
+export const CA_POLICY_UPDATE_READ_SCOPES = ["https://graph.microsoft.com/Policy.Read.All"];
+// The only top-level policy properties this slice may send. Anything else
+// (id, createdDateTime, modifiedDateTime, ...) has no flag and can never
+// reach the PATCH body.
+export const CA_POLICY_WRITABLE_FIELDS = ["displayName", "state", "conditions", "grantControls", "sessionControls"];
+export const CA_POLICY_STATES = ["enabled", "enabledForReportingButNotEnforced", "disabled"];
+const FLAG_TO_FIELD = {
+    "display-name": "displayName",
+    "state": "state",
+    "conditions": "conditions",
+    "grant-controls": "grantControls",
+    "session-controls": "sessionControls",
+};
+const ENFORCEMENT_FIELDS = ["state", "conditions", "grantControls", "sessionControls"];
+const PERMISSION_GUIDANCE = "Needs D/A Policy.Read.All plus Policy.ReadWrite.ConditionalAccess (least-privileged pair per conditionalaccesspolicy-update v1.0, rechecked 2026-10-04)";
+const ROLE_GUIDANCE = "Delegated callers additionally need Conditional Access Administrator or Security Administrator; CA needs P1, risk-based CA needs P2";
+const CONCURRENCY_NOTE = "Graph documents no ETag or If-Match precondition for this endpoint, so fresh reads do not make the update atomic: another actor can change the policy between the read and the PATCH. The command sends no If-Match and promises no concurrency protection";
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map(key => [key, canonicalize(value[key])]));
+    }
+    return value;
+}
+function containsRedactedValue(value) {
+    return value === REDACTED || (value !== null && typeof value === "object"
+        && Object.values(value).some(containsRedactedValue));
+}
+function sameValue(current, proposed) {
+    return !containsRedactedValue(current)
+        && JSON.stringify(canonicalize(current)) === JSON.stringify(canonicalize(proposed));
+}
+function parseJsonObject(raw, flag, help) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new AxiError(`--${flag} must be a JSON object`, "VALIDATION_ERROR", [help]);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new AxiError(`--${flag} must be a JSON object`, "VALIDATION_ERROR", [help]);
+    }
+    return parsed;
+}
+// Maps exactly the reviewed-field flags to PATCH properties. Unreviewed
+// Graph properties have no flag, so resolveCommand already refuses them as
+// unknown flags before credentials; this parser additionally refuses empty,
+// mistyped and unparsable reviewed values.
+export function parsePolicyUpdate(raw, help) {
+    const payload = {};
+    for (const [flag, field] of Object.entries(FLAG_TO_FIELD)) {
+        const value = raw[flag];
+        if (value === undefined)
+            continue;
+        const text = String(value);
+        if (field === "displayName") {
+            if (!text.trim())
+                throw new AxiError("--display-name needs a non-empty policy name", "VALIDATION_ERROR", [help]);
+            payload[field] = text;
+        }
+        else if (field === "state") {
+            if (!CA_POLICY_STATES.includes(text)) {
+                throw new AxiError(`--state must be ${CA_POLICY_STATES.join("|")}`, "VALIDATION_ERROR", [help]);
+            }
+            payload[field] = text;
+        }
+        else {
+            payload[field] = parseJsonObject(text, flag, help);
+        }
+    }
+    if (Object.keys(payload).length === 0) {
+        throw new AxiError("Policy update needs at least one reviewed field: --display-name, --state, --conditions, --grant-controls or --session-controls", "VALIDATION_ERROR", [help]);
+    }
+    return payload;
+}
+export function caPolicyDefinition(policyId, payload) {
+    const target = policyId.trim();
+    return {
+        operation: CA_POLICY_UPDATE_OPERATION,
+        method: "PATCH",
+        version: "v1.0",
+        path: `/v1.0/identity/conditionalAccess/policies/${encodeGraphPathSegment(target)}`,
+        effect: "disruptive",
+        target,
+        payload: { ...payload },
+    };
+}
+async function readPolicy(session, profile, readOperation, policyId) {
+    const raw = await session.execute({
+        profile,
+        operation: readOperation,
+        params: { "conditionalAccessPolicy-id": policyId },
+        query: { $select: "id,displayName,state,conditions,grantControls,sessionControls" },
+        ...(profile.mode === "application" ? {} : { scopes: [...CA_POLICY_UPDATE_READ_SCOPES] }),
+    });
+    if (raw !== null && typeof raw === "object" && !Array.isArray(raw)
+        && typeof raw["id"] === "string" && raw["id"].length > 0) {
+        return raw;
+    }
+    throw new AxiError("Graph returned a policy without an object ID", "GRAPH_ERROR", [
+        "Read back the policy before attempting an update",
+    ]);
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every(entry => typeof entry === "string") ? [...value] : null;
+}
+export function analyzeLockout(current, payload) {
+    const effective = { ...current, ...payload };
+    const state = effective["state"];
+    if (typeof state !== "string") {
+        return { available: false, reason: "policy state is unreadable, so lockout risk cannot be assessed" };
+    }
+    if (state !== "enabled") {
+        return { available: true, level: "none", findings: [`policy state '${state}' does not enforce access`] };
+    }
+    const conditions = effective["conditions"];
+    if (conditions === null || typeof conditions !== "object" || Array.isArray(conditions)) {
+        return { available: false, reason: "policy conditions are unreadable, so lockout risk cannot be assessed" };
+    }
+    const users = conditions["users"];
+    if (users === null || typeof users !== "object" || Array.isArray(users)) {
+        return { available: false, reason: "policy user scope is unreadable, so lockout risk cannot be assessed" };
+    }
+    const includeUsers = stringArray(users["includeUsers"]);
+    if (includeUsers === null) {
+        return { available: false, reason: "policy user scope is unreadable, so lockout risk cannot be assessed" };
+    }
+    const excludeUsers = stringArray(users["excludeUsers"]);
+    const excludeGroups = stringArray(users["excludeGroups"]);
+    if (excludeUsers === null || excludeGroups === null) {
+        return { available: false, reason: "policy exclusions are unreadable, so lockout risk cannot be assessed" };
+    }
+    for (const field of ["includeGroups", "includeRoles"]) {
+        const entries = users[field];
+        if (entries !== undefined && stringArray(entries) === null) {
+            return { available: false, reason: "policy user scope is unreadable, so lockout risk cannot be assessed" };
+        }
+    }
+    const roles = users["excludeRoles"];
+    const excludeRoles = roles === undefined ? [] : stringArray(roles);
+    if (excludeRoles === null) {
+        return { available: false, reason: "policy exclusions are unreadable, so lockout risk cannot be assessed" };
+    }
+    const grantControls = effective["grantControls"];
+    if (grantControls === null || typeof grantControls !== "object" || Array.isArray(grantControls)) {
+        return { available: false, reason: "policy grant controls are unreadable, so lockout risk cannot be assessed" };
+    }
+    const builtIn = grantControls["builtInControls"];
+    const controls = builtIn === undefined ? [] : stringArray(builtIn);
+    if (controls === null) {
+        return { available: false, reason: "policy grant controls are unreadable, so lockout risk cannot be assessed" };
+    }
+    const clients = stringArray(conditions["clientAppTypes"]);
+    const applications = conditions["applications"];
+    if (clients === null || applications === null || typeof applications !== "object" || Array.isArray(applications)) {
+        return { available: false, reason: "policy client or application scope is unreadable, so lockout risk cannot be assessed" };
+    }
+    const includedApps = stringArray(applications["includeApplications"]);
+    const excludedApps = stringArray(applications["excludeApplications"]);
+    if (includedApps === null || excludedApps === null) {
+        return { available: false, reason: "policy application inclusions or exclusions are unreadable, so lockout risk cannot be assessed" };
+    }
+    const coversAdminClients = clients.includes("all")
+        || (clients.includes("browser") && clients.includes("mobileAppsAndDesktopClients"));
+    const coversAdminApps = (includedApps.includes("All") || includedApps.includes("MicrosoftAdminPortals"))
+        && !excludedApps.includes("All") && !excludedApps.includes("MicrosoftAdminPortals");
+    let narrowedConditions = false;
+    for (const field of ["signInRiskLevels", "userRiskLevels"]) {
+        const levels = stringArray(conditions[field]);
+        if (levels !== null && levels.length > 0
+            && levels.every(level => ["low", "medium", "high"].includes(level)))
+            narrowedConditions = true;
+    }
+    for (const [field, includeField, excludeField, all] of [
+        ["platforms", "includePlatforms", "excludePlatforms", "all"],
+        ["locations", "includeLocations", "excludeLocations", "All"],
+    ]) {
+        const scope = conditions[field];
+        if (scope == null)
+            continue;
+        if (typeof scope !== "object" || Array.isArray(scope)) {
+            return { available: false, reason: `policy ${field} scope is unreadable, so lockout risk cannot be assessed` };
+        }
+        const included = stringArray(scope[includeField]);
+        const excluded = stringArray(scope[excludeField]);
+        if (included === null || excluded === null) {
+            return { available: false, reason: `policy ${field} inclusions or exclusions are unreadable, so lockout risk cannot be assessed` };
+        }
+        if (!included.includes(all) || excluded.length > 0)
+            narrowedConditions = true;
+    }
+    if (includeUsers.includes("All") && controls.includes("block")
+        && coversAdminClients && coversAdminApps && !narrowedConditions) {
+        return {
+            available: true,
+            level: "refused",
+            findings: ["enabled all-users block policy covers browser and modern clients on all cloud apps or admin portals; no verified exclusion protects admins and break-glass access, so full lockout is refused"],
+        };
+    }
+    return {
+        available: true,
+        level: "elevated",
+        findings: [!coversAdminClients || !coversAdminApps || narrowedConditions
+                ? "scoped warning: client, application or other conditions limit coverage; this policy may still affect admins and break-glass access and requires acknowledgement"
+                : "enabled policy may affect admins and break-glass access; protected-account coverage cannot be established from policy targeting alone"],
+    };
+}
+function touchesEnforcement(payload) {
+    return ENFORCEMENT_FIELDS.some(field => Object.hasOwn(payload, field));
+}
+function executeHint(policyId, elevated, profileName) {
+    const shell = (value) => /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+    return `mg-axi entra conditional-access policy update --id ${shell(policyId)} <reviewed field flags>`
+        + ` --execute --confirm ${shell(policyId)}${elevated ? " --acknowledge-lockout-risk" : ""}`
+        + ` --profile ${shell(profileName)}`;
+}
+function showHint(policyId, profileName) {
+    const shell = (value) => /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+    return `mg-axi entra conditional-access policy show --id ${shell(policyId)} --profile ${shell(profileName)}`;
+}
+function assertLockoutGates(payload, assessment, acknowledged) {
+    if (!touchesEnforcement(payload))
+        return;
+    if (!assessment.available) {
+        throw new AxiError(`Refusing policy update: ${assessment.reason}; the operation stays disabled without lockout analysis`, "OPERATION_BLOCKED", ["Read back the policy and retry only when its conditions, user scope and grant controls are verifiable"]);
+    }
+    if (assessment.level === "refused") {
+        throw new AxiError(`Refusing policy update: ${assessment.findings.join("; ")}`, "OPERATION_BLOCKED", [
+            "Narrow user, client or application conditions, or replace the block control before retrying",
+            "This refusal cannot be overridden with an acknowledgement flag",
+        ]);
+    }
+    if (assessment.level === "elevated" && !acknowledged) {
+        throw new AxiError("Policy update needs --acknowledge-lockout-risk: protected-account coverage cannot be established from policy targeting alone", "LOCKOUT_ACK_REQUIRED", ["Re-run with --acknowledge-lockout-risk after confirming emergency-access coverage"]);
+    }
+}
+export async function updateCaPolicy(args) {
+    const { session, coordinator, flags, profile, profileName, readOperation, help } = args;
+    const policyId = String(flags.id ?? "").trim();
+    if (!policyId)
+        throw new AxiError("--id needs a Conditional Access policy object ID", "VALIDATION_ERROR", [help]);
+    const version = String(flags["api-version"] ?? "v1.0");
+    if (version !== "v1.0") {
+        throw new AxiError(`--api-version ${version} cannot mutate: WRITE-04 binds PATCH /identity/conditionalAccess/policies/{id} to v1.0; beta writes stay blocked`, "VALIDATION_ERROR", [help]);
+    }
+    const payload = parsePolicyUpdate(flags, help);
+    const acknowledged = flags["acknowledge-lockout-risk"] === true;
+    const definition = caPolicyDefinition(policyId, payload);
+    const execute = flags.execute === true;
+    // Gates first: preview refuses read-only, unscoped and beta-bound profiles
+    // before any read, credential or transport.
+    coordinator.preview(definition);
+    if (execute) {
+        if (flags.confirm === undefined) {
+            throw new AxiError(`blocked: disruptive PATCH needs --confirm '${definition.target}'`, "CONFIRM_REQUIRED", [`Re-run with --confirm '${definition.target}'`]);
+        }
+        if (String(flags.confirm) !== definition.target) {
+            throw new AxiError(`blocked: --confirm '${flags.confirm}' does not match target '${definition.target}'`, "CONFIRM_MISMATCH", [`Re-run with --confirm '${definition.target}'`]);
+        }
+    }
+    const current = await readPolicy(session, profile, readOperation, policyId);
+    const changes = Object.keys(payload).map(field => ({
+        field,
+        current: redactGraphValue(Object.hasOwn(current, field) ? current[field] : null),
+        proposed: redactGraphValue(payload[field]),
+    }));
+    // A missing property reads as absent, never as null: only an explicitly
+    // stored equal value counts as already-desired.
+    const noop = Object.keys(payload).every(field => sameValue(Object.hasOwn(current, field) ? current[field] : undefined, payload[field]));
+    const assessment = analyzeLockout(current, payload);
+    const previewUrl = coordinator.preview(definition).url;
+    const preview = {
+        operation: definition.operation,
+        target: definition.target,
+        method: definition.method,
+        url: previewUrl,
+        effect: definition.effect,
+        changes,
+        noop,
+        lockout: assessment,
+        concurrency: CONCURRENCY_NOTE,
+    };
+    if (!execute) {
+        const elevated = assessment.available && assessment.level === "elevated";
+        return {
+            preview,
+            help: [
+                ...(noop
+                    ? ["Already in the desired state; no update is needed"]
+                    : [executeHint(policyId, elevated, profileName)]),
+                ...(!noop
+                    ? ["Policy updates are disruptive: the --execute run needs the typed --confirm value shown above"]
+                    : []),
+                ...(elevated && !noop ? ["Unverified admin and break-glass coverage needs --acknowledge-lockout-risk on the --execute run"] : []),
+                showHint(policyId, profileName),
+            ],
+        };
+    }
+    if (noop)
+        return { noop: true, policy: { id: current["id"] } };
+    assertLockoutGates(payload, assessment, acknowledged);
+    const readState = async () => {
+        const fresh = await readPolicy(session, profile, readOperation, policyId);
+        assertLockoutGates(payload, analyzeLockout(fresh, payload), acknowledged);
+        return fresh;
+    };
+    const result = await coordinator.execute(definition, {
+        execute: true,
+        confirm: String(flags.confirm),
+        ...(profile.mode === "application" ? {} : { scopes: [...CA_POLICY_UPDATE_SCOPES] }),
+        readState,
+        isNoop: fresh => Object.keys(payload).every(field => sameValue(fresh[field], payload[field])),
+    });
+    if (result.kind === "failed") {
+        throw new AxiError(`Graph refused the policy update (status ${result.status})`, "GRAPH_ERROR", [
+            ...(result.status === 403 ? [PERMISSION_GUIDANCE, ROLE_GUIDANCE] : []),
+            `Audit ${result.auditId} recorded the refusal; read back '${policyId}' and never replay this intent`,
+        ]);
+    }
+    if (result.kind === "unknown") {
+        throw new AxiError(`Update of '${policyId}' may or may not have been applied (audit ${result.auditId}); never replay this intent`, "OUTCOME_UNKNOWN", [
+            `Audit ${result.auditId} recorded the uncertain outcome; read back '${policyId}' with ${showHint(policyId, profileName)} before doing anything else`,
+            "Never replay this intent",
+        ]);
+    }
+    // Anything but success, failure or uncertainty is the verified no-op:
+    // dry-run needs execute !== true, always set above.
+    if (result.kind !== "success") {
+        return { noop: true, policy: { id: current["id"] } };
+    }
+    // Success carries no proof: policy-update answers 204 with an empty body.
+    // The coordinator outcome is the only record; verify with policy show.
+    return { policy: { id: current["id"] }, auditId: result.auditId, help: [showHint(policyId, profileName)] };
+}