@knowttl/mg-axi 0.1.0

package/dist/entra-organization.js

@@ -0,0 +1,398 @@
+import { AxiError } from "axi-sdk-js";
+// EXT-01 organization subfamily: the read mapping behind
+// `mg-axi entra organization list/show`, the default-branding read behind
+// `mg-axi entra organization branding show`, and the branding-localization
+// reads behind `mg-axi entra organization branding-localization
+// list/show`. Operation construction stays beside its command; the shared
+// session owns URLs, credentials, paging, retries and error translation,
+// and the SDK owns TOON rendering. This module only maps flags to session
+// calls and projects rows for compact output.
+//
+// Reviewed against the v1.0 organization-list, organization-get,
+// organizationalbranding-get, organizationalbranding-list-localizations and
+// organizationalbrandinglocalization-get operation documentation on
+// 2026-10-04. Organization list/get take D User.Read for restricted basics
+// (id, displayName and verifiedDomains only; every other property returns
+// null) or Organization.Read.All for full metadata, and A
+// Organization.Read.All; delegated callers additionally need a supported
+// Entra role (Directory Readers and Global Reader are among the supported
+// least-privilege roles). Branding and localization reads take D User.Read
+// least-privileged (OrganizationalBranding.Read.All is the purpose-built
+// delegated alternative) and A OrganizationalBranding.Read.All; delegated
+// callers additionally need Global Reader or Organizational Branding
+// Administrator least-privileged. Personal Microsoft accounts are not
+// supported on any of these reads. No P1/P2 prerequisite is stated for the
+// reads, but configuring custom branding itself needs P1/P2. Contact
+// fields on the organization (businessPhones, notification mails) are
+// personal data. Every reviewed read documents $select only, so none of
+// these leaves offers --filter. The branding GET documents Accept-Language
+// as required; the session sends `Accept-Language: 0` on that route to read
+// the default branding, and locale variants come from the localizations
+// collection. Stream image properties (bannerLogo, backgroundImage and
+// friends) need their own binary-output contract and stay out of this
+// slice, as do certificateBasedAuthConfiguration, extensions, beta-only
+// settings/partnerInformation/themes and the POST lookup actions. No
+// organization mutation exists in this slice.
+// Every organization property this slice may request or display, matching
+// the reviewed raw surface. Anything else fails before credentials.
+export const KNOWN_ORGANIZATION_FIELDS = [
+    "id",
+    "deletedDateTime",
+    "businessPhones",
+    "city",
+    "country",
+    "countryLetterCode",
+    "createdDateTime",
+    "defaultUsageLocation",
+    "displayName",
+    "isMultipleDataLocationsForServicesEnabled",
+    "marketingNotificationEmails",
+    "onPremisesLastSyncDateTime",
+    "onPremisesSyncEnabled",
+    "partnerTenantType",
+    "postalCode",
+    "preferredLanguage",
+    "privacyProfile",
+    "provisionedPlans",
+    "securityComplianceNotificationMails",
+    "securityComplianceNotificationPhones",
+    "state",
+    "street",
+    "technicalNotificationMails",
+    "tenantType",
+    "assignedPlans",
+    "verifiedDomains",
+];
+const KNOWN_ORGANIZATIONS = new Set(KNOWN_ORGANIZATION_FIELDS);
+// Every non-Stream branding property this slice may request or display.
+// Stream image properties (backgroundImage, bannerLogo, customCSS, favicon,
+// headerLogo, squareLogo, squareLogoDark) are real server properties but
+// need a binary-output contract this text CLI does not have; requesting one
+// fails with a targeted hint instead of an unknown-property error.
+export const KNOWN_BRANDING_FIELDS = [
+    "id",
+    "backgroundColor",
+    "backgroundImageRelativeUrl",
+    "bannerLogoRelativeUrl",
+    "cdnList",
+    "signInPageText",
+    "squareLogoRelativeUrl",
+    "usernameHintText",
+    "customAccountResetCredentialsUrl",
+    "customCannotAccessYourAccountText",
+    "customCannotAccessYourAccountUrl",
+    "customCSSRelativeUrl",
+    "customForgotMyPasswordText",
+    "customPrivacyAndCookiesText",
+    "customPrivacyAndCookiesUrl",
+    "customResetItNowText",
+    "customTermsOfUseText",
+    "customTermsOfUseUrl",
+    "faviconRelativeUrl",
+    "headerBackgroundColor",
+    "headerLogoRelativeUrl",
+    "squareLogoDarkRelativeUrl",
+];
+const KNOWN_BRANDING = new Set(KNOWN_BRANDING_FIELDS);
+const STREAM_BRANDING_FIELDS = new Set([
+    "backgroundImage",
+    "bannerLogo",
+    "customCSS",
+    "favicon",
+    "headerLogo",
+    "squareLogo",
+    "squareLogoDark",
+]);
+// Compact organization rows: the tenant identity, display name, tenant kind
+// and the verified domains that name the tenant on the network.
+const DEFAULT_ORGANIZATION_LIST_SELECT = ["id", "displayName", "tenantType", "verifiedDomains"];
+// Show rows: the full reviewed organization set, including the technical
+// notification mails and privacy profile.
+const DEFAULT_ORGANIZATION_SHOW_SELECT = [...KNOWN_ORGANIZATION_FIELDS];
+// Branding show rows: the full reviewed non-Stream set.
+const DEFAULT_BRANDING_SHOW_SELECT = [...KNOWN_BRANDING_FIELDS];
+// Compact localization rows: the locale id and the sign-in text a user
+// actually sees.
+const DEFAULT_LOCALIZATION_LIST_SELECT = ["id", "signInPageText", "usernameHintText", "backgroundColor"];
+// Localization show rows: the full reviewed non-Stream set.
+const DEFAULT_LOCALIZATION_SHOW_SELECT = [...KNOWN_BRANDING_FIELDS];
+// Delegated defaults are operation-specific; application profiles use their
+// configured .default audience and reject --scopes.
+export const DEFAULT_ORGANIZATION_SCOPES = ["https://graph.microsoft.com/Organization.Read.All"];
+export const DEFAULT_BRANDING_SCOPES = ["https://graph.microsoft.com/User.Read"];
+const TRUNCATE_AT = 500;
+function fieldList(raw, known, knownList, flag, help, streamHint) {
+    const parts = String(raw)
+        .split(",")
+        .map(part => part.trim())
+        .filter(part => part.length > 0);
+    if (!parts.length)
+        throw new AxiError(`--${flag} needs at least one property`, "VALIDATION_ERROR", [help]);
+    const fields = [];
+    for (const part of parts) {
+        if (streamHint !== undefined && STREAM_BRANDING_FIELDS.has(part)) {
+            throw new AxiError(`${part} is a Stream image route served by a later piece; this read returns non-Stream branding metadata only`, "VALIDATION_ERROR", [help, streamHint]);
+        }
+        if (!known.has(part)) {
+            throw new AxiError(`Unknown organization property ${part} in --${flag}`, "VALIDATION_ERROR", [
+                help,
+                `Known properties: ${knownList.join(", ")}`,
+            ]);
+        }
+        if (!fields.includes(part))
+            fields.push(part);
+    }
+    return fields;
+}
+function scopesFor(flags, defaults, profile, help) {
+    if (profile.mode === "application") {
+        if (flags.scopes !== undefined) {
+            throw new AxiError("Application profiles use the configured Graph .default audience; delegated scopes are unavailable", "VALIDATION_ERROR", [help, "mg-axi profile show --profile <name>"]);
+        }
+        return undefined;
+    }
+    if (flags.scopes === undefined)
+        return [...defaults];
+    const scopes = String(flags.scopes)
+        .split(",")
+        .map(scope => scope.trim())
+        .filter(scope => scope.length > 0);
+    return scopes;
+}
+function truncateValue(value, full) {
+    const truncate = (text) => full || text.length <= TRUNCATE_AT
+        ? { value: text, truncated: false }
+        : { value: `${text.slice(0, TRUNCATE_AT)}... (truncated, ${text.length} chars total)`, truncated: true };
+    if (typeof value === "string")
+        return truncate(value);
+    if (Array.isArray(value) && value.every(entry => typeof entry === "string")) {
+        const projected = value.map(truncate);
+        return { value: projected.map(entry => entry.value), truncated: projected.some(entry => entry.truncated) };
+    }
+    return { value, truncated: false };
+}
+// Local projection preserves Graph's null/missing distinction: an explicit
+// null stays null, an absent property stays absent and is never synthesized.
+// This matters for User.Read restricted basics, where every property outside
+// id, displayName and verifiedDomains returns null.
+function project(row, fields, full) {
+    const source = row !== null && typeof row === "object" && !Array.isArray(row) ? row : {};
+    const projected = {};
+    let truncated = false;
+    for (const field of fields) {
+        if (!Object.hasOwn(source, field))
+            continue;
+        const result = truncateValue(source[field], full);
+        projected[field] = result.value;
+        truncated = truncated || result.truncated;
+    }
+    return { row: projected, truncated };
+}
+function selectedFields(flags, known, knownList, defaults, help, streamHint) {
+    const select = flags.select === undefined ? [...defaults] : fieldList(flags.select, known, knownList, "select", help, streamHint);
+    const fields = flags.fields === undefined ? [...select] : fieldList(flags.fields, known, knownList, "fields", help, streamHint);
+    const missing = fields.find(field => !select.includes(field));
+    if (missing) {
+        throw new AxiError(`--fields ${missing} was not fetched; request it with --select`, "VALIDATION_ERROR", [help]);
+    }
+    return { select, fields };
+}
+function profileHint(profileName) {
+    return `--profile ${shellValue(profileName)}`;
+}
+function shellValue(value) {
+    return /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function fullHint(command, flags, profileName) {
+    const args = Object.entries({ ...flags, profile: profileName, full: true })
+        .map(([name, value]) => value === true ? `--${name}` : `--${name} ${shellValue(String(value))}`);
+    return `mg-axi ${command} ${args.join(" ")}`;
+}
+// Denials carry the session's generic grant/role/licence cause; each
+// operation adds the scope, roles and licensing that actually unlock it,
+// because a 403 alone never says which prerequisite is missing.
+function withGuidance(hints, run) {
+    return run().catch(error => {
+        if (error instanceof AxiError && error.code === "GRAPH_ERROR" && /\(403\)/.test(error.message)) {
+            throw new AxiError(error.message, "GRAPH_ERROR", [...hints, ...error.suggestions]);
+        }
+        throw error;
+    });
+}
+const ORGANIZATION_DENIAL_HINTS = [
+    "Organization reads need Organization.Read.All for full metadata plus a supported Entra role for delegated access (Directory Readers and Global Reader are among the supported least-privilege roles), or admin-consented Organization.Read.All for application access; delegated User.Read returns only id, displayName and verifiedDomains with every other property null",
+    "Personal Microsoft accounts are not supported for organization reads",
+    "No P1/P2 prerequisite is stated for organization reads; never diagnose licence solely from HTTP 403",
+];
+const BRANDING_DENIAL_HINTS = [
+    "Branding reads need User.Read least-privileged or the purpose-built OrganizationalBranding.Read.All (Organization.Read.All also works) plus Global Reader or Organizational Branding Administrator for delegated access, or admin-consented OrganizationalBranding.Read.All for application access",
+    "Personal Microsoft accounts are not supported for branding reads",
+    "Configuring custom branding needs P1/P2; a branding 404 may indicate unconfigured branding or a missing or inaccessible organization; never diagnose licence solely from HTTP 403",
+];
+const STREAM_HINT = "Stream image properties (backgroundImage, bannerLogo, customCSS, favicon, headerLogo, squareLogo, squareLogoDark) are served by a later piece with its own binary-output contract";
+// Restoring the saved select keeps cursor resumes lossless when --select is
+// omitted. Organization and localization lists document $select only, so
+// neither leaf offers --filter: strict input validation refuses the flag
+// before credentials instead of forwarding a misleading request.
+function collectionCommon(session, flags, known, knownList, defaults, defaultScopes, operation, help, profile) {
+    const cursor = flags.cursor === undefined ? undefined : String(flags.cursor);
+    if (cursor !== undefined && !cursor.trim())
+        throw new AxiError("--cursor needs the opaque cursor from a partial result", "VALIDATION_ERROR", [help]);
+    const saved = cursor === undefined ? undefined : session.cursorQuery(operation, cursor);
+    const { select, fields } = selectedFields(flags, known, knownList, saved?.["$select"] === undefined ? defaults : fieldList(saved["$select"], known, knownList, "select", help), help);
+    return { cursor, select, fields, scopes: scopesFor(flags, defaultScopes, profile, help), full: flags.full === true };
+}
+function collectArgs(profile, operation, common, flags, help) {
+    const query = { $select: common.select.join(",") };
+    const args = { profile, operation, query, scopes: common.scopes };
+    if (common.cursor !== undefined)
+        args.cursor = common.cursor;
+    if (flags.all === true) {
+        if (flags.limit !== undefined)
+            throw new AxiError("--limit and --all cannot be combined", "VALIDATION_ERROR", [help]);
+    }
+    else {
+        args.limit = flags.limit === undefined ? 100 : Number(flags.limit);
+    }
+    return args;
+}
+function resumeHint(profileName) {
+    return `Resume losslessly with the same flags plus --cursor <cursor-from-output> ${profileHint(profileName)}`;
+}
+function organizationId(flags, help, flag) {
+    const id = String(flags[flag]);
+    if (!id.trim())
+        throw new AxiError(`--${flag} needs the tenant organization UUID`, "VALIDATION_ERROR", [help]);
+    return id;
+}
+function singleResult(raw, fields, full, kind) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new AxiError(`Graph returned a malformed ${kind} body`, "GRAPH_ERROR", [
+            `Single-${kind} reads carry one ${kind} object; treat anything else as unknown, not empty`,
+        ]);
+    }
+    return project(raw, fields, full);
+}
+export async function listOrganizations(session, flags, profile, operation, help, profileName) {
+    const common = collectionCommon(session, flags, KNOWN_ORGANIZATIONS, KNOWN_ORGANIZATION_FIELDS, DEFAULT_ORGANIZATION_LIST_SELECT, DEFAULT_ORGANIZATION_SCOPES, operation, help, profile);
+    const result = await withGuidance(ORGANIZATION_DENIAL_HINTS, () => session.collect(collectArgs(profile, operation, common, flags, help)));
+    const effectiveFlags = { ...flags, select: result.query.$select ?? DEFAULT_ORGANIZATION_LIST_SELECT.join(",") };
+    const organizations = [];
+    let truncated = false;
+    for (const row of result.value) {
+        const projected = project(row, common.fields, common.full);
+        organizations.push(projected.row);
+        truncated = truncated || projected.truncated;
+    }
+    const showHint = `mg-axi entra organization show --id <organization-id> ${profileHint(profileName)}`;
+    const filterNote = "Organization lists offer no --filter: Graph documents $select only for /organization";
+    const truncationHints = truncated ? [fullHint("entra organization list", effectiveFlags, profileName)] : [];
+    if (!result.complete) {
+        return {
+            organizations,
+            count: { returned: organizations.length, complete: false, reason: result.reason },
+            cursor: result.cursor,
+            help: [...truncationHints, resumeHint(profileName), showHint, filterNote],
+        };
+    }
+    const count = { returned: organizations.length, complete: true };
+    if (!organizations.length) {
+        return {
+            organizations,
+            count,
+            help: [filterNote, "0 organizations matched; the absence of results is the answer, not an error"],
+        };
+    }
+    return { organizations, count, help: [...truncationHints, showHint, filterNote] };
+}
+export async function showOrganization(session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, KNOWN_ORGANIZATIONS, KNOWN_ORGANIZATION_FIELDS, DEFAULT_ORGANIZATION_SHOW_SELECT, help);
+    const scopes = scopesFor(flags, DEFAULT_ORGANIZATION_SCOPES, profile, help);
+    const full = flags.full === true;
+    const raw = await withGuidance(ORGANIZATION_DENIAL_HINTS, () => session.execute({
+        profile,
+        operation,
+        params: { "organization-id": organizationId(flags, help, "id") },
+        query: { $select: select.join(",") },
+        scopes,
+    }));
+    const { row, truncated } = singleResult(raw, fields, full, "organization");
+    const helpHints = truncated ? [fullHint("entra organization show", flags, profileName)] : [];
+    if (helpHints.length)
+        return { organization: row, help: helpHints };
+    return { organization: row };
+}
+export async function showBranding(session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, KNOWN_BRANDING, KNOWN_BRANDING_FIELDS, DEFAULT_BRANDING_SHOW_SELECT, help, STREAM_HINT);
+    const scopes = scopesFor(flags, DEFAULT_BRANDING_SCOPES, profile, help);
+    const full = flags.full === true;
+    const organization = organizationId(flags, help, "organization");
+    const raw = await withGuidance(BRANDING_DENIAL_HINTS, () => session.execute({
+        profile,
+        operation,
+        params: { "organization-id": organization },
+        query: { $select: select.join(",") },
+        scopes,
+    }));
+    const { row, truncated } = singleResult(raw, fields, full, "branding");
+    const helpHints = [
+        ...(truncated ? [fullHint("entra organization branding show", flags, profileName)] : []),
+        `mg-axi entra organization branding-localization list --organization ${shellValue(organization)} ${profileHint(profileName)}`,
+    ];
+    return { branding: row, help: helpHints };
+}
+export async function listBrandingLocalizations(session, flags, profile, operation, help, profileName) {
+    const common = collectionCommon(session, flags, KNOWN_BRANDING, KNOWN_BRANDING_FIELDS, DEFAULT_LOCALIZATION_LIST_SELECT, DEFAULT_BRANDING_SCOPES, operation, help, profile);
+    const args = collectArgs(profile, operation, common, flags, help);
+    const organization = organizationId(flags, help, "organization");
+    args.params = { "organization-id": organization };
+    const result = await withGuidance(BRANDING_DENIAL_HINTS, () => session.collect(args));
+    const effectiveFlags = { ...flags, select: result.query.$select ?? DEFAULT_LOCALIZATION_LIST_SELECT.join(",") };
+    const localizations = [];
+    let truncated = false;
+    for (const row of result.value) {
+        const projected = project(row, common.fields, common.full);
+        localizations.push(projected.row);
+        truncated = truncated || projected.truncated;
+    }
+    const showHint = `mg-axi entra organization branding-localization show --organization ${shellValue(organization)} --id <locale-id> ${profileHint(profileName)}`;
+    const filterNote = "Localization lists offer no --filter: Graph documents $select only for branding localizations";
+    const truncationHints = truncated ? [fullHint("entra organization branding-localization list", effectiveFlags, profileName)] : [];
+    if (!result.complete) {
+        return {
+            brandingLocalizations: localizations,
+            count: { returned: localizations.length, complete: false, reason: result.reason },
+            cursor: result.cursor,
+            help: [...truncationHints, resumeHint(profileName), showHint, filterNote],
+        };
+    }
+    const count = { returned: localizations.length, complete: true };
+    if (!localizations.length) {
+        return {
+            brandingLocalizations: localizations,
+            count,
+            help: [filterNote, "0 branding localizations matched; the absence of results is the answer, not an error"],
+        };
+    }
+    return { brandingLocalizations: localizations, count, help: [...truncationHints, showHint, filterNote] };
+}
+export async function showBrandingLocalization(session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, KNOWN_BRANDING, KNOWN_BRANDING_FIELDS, DEFAULT_LOCALIZATION_SHOW_SELECT, help, STREAM_HINT);
+    const scopes = scopesFor(flags, DEFAULT_BRANDING_SCOPES, profile, help);
+    const full = flags.full === true;
+    const organization = organizationId(flags, help, "organization");
+    const locale = String(flags.id);
+    if (!locale.trim())
+        throw new AxiError("--id needs the branding locale id, for example fr-FR", "VALIDATION_ERROR", [help]);
+    const raw = await withGuidance(BRANDING_DENIAL_HINTS, () => session.execute({
+        profile,
+        operation,
+        params: { "organization-id": organization, "organizationalBrandingLocalization-id": locale },
+        query: { $select: select.join(",") },
+        scopes,
+    }));
+    const { row, truncated } = singleResult(raw, fields, full, "branding localization");
+    if (truncated)
+        return { brandingLocalization: row, help: [fullHint("entra organization branding-localization show", flags, profileName)] };
+    return { brandingLocalization: row };
+}

package/dist/entra-risk-dismiss.js

@@ -0,0 +1,191 @@
+import { AxiError } from "axi-sdk-js";
+import { RISKY_USER_DENIAL_HINTS, withGuidance } from "./entra-risk.js";
+// WRITE-05: dismiss the risk of one explicitly named user through an action
+// write leaf (`mg-axi entra risky-user dismiss --user <risky-user-id>`), via
+// POST /identityProtection/riskyUsers/dismiss with a single-element
+// { userIds: [...] } body. There is no bulk form: a comma in --user is a
+// usage error and unknown flags (including any plural --user-ids) fail in
+// the strict catalogue before credentials. Preview reads the user's current
+// risk state through the READ-06 risky-user show route; an already-dismissed
+// user is a no-op. Dismissal answers 204 with an empty body, so after a send
+// the command rereads the user and reports a conflict when the state is not
+// dismissed, mirroring WRITE-02.
+//
+// Reviewed against the v1.0 riskyuser-dismiss operation documentation on
+// REVIEWED_ON: POST /identityProtection/riskyUsers/dismiss carries
+// { userIds: [...] } and answers 204 No Content. The least-privileged
+// permission is D/A IdentityRiskyUser.ReadWrite.All; delegated callers
+// additionally need Security Administrator (least-privileged role) and the
+// riskyUsers API requires a Microsoft Entra ID P2 licence. Dismissal sets
+// the user's risk level to none; it is not remediation - it resets no
+// credential and revokes no session. Every gate in src/mutations.ts stays in
+// force through the coordinator: hand-enabled profile, immutable scope,
+// preview, --execute, durable journal intent/outcome, no replay,
+// coordinator-only authorization and read-only enforced at send time.
+export const REVIEWED_ON = "2026-10-04";
+// Scope name a profile hand-enables in its writes.operations allowlist.
+export const RISKY_USER_DISMISS_OPERATION = "entra.risky-user.dismiss";
+export const RISKY_USER_DISMISS_WRITE_SCOPES = ["https://graph.microsoft.com/IdentityRiskyUser.ReadWrite.All"];
+export const RISKY_USER_DISMISS_READ_SCOPES = ["https://graph.microsoft.com/IdentityRiskyUser.Read.All"];
+const RISK_STATE_SELECT = "id,userPrincipalName,riskLevel,riskState,riskDetail,riskLastUpdatedDateTime";
+const PERMISSION_GUIDANCE = "Needs D/A IdentityRiskyUser.ReadWrite.All (least-privileged per riskyuser-dismiss v1.0, rechecked 2026-10-04)";
+const ROLE_GUIDANCE = "Delegated callers additionally need Security Administrator (least-privileged role for this action)";
+const LICENCE_GUIDANCE = "The riskyUsers API requires a Microsoft Entra ID P2 licence; without it Graph denies the dismissal";
+const REMEDIATION_NOTE = "Dismissal is not remediation: it records the user's risk as dismissed without resetting credentials or revoking sessions";
+export function riskDismissDefinition(user) {
+    const target = user.trim();
+    return {
+        operation: RISKY_USER_DISMISS_OPERATION,
+        method: "POST",
+        version: "v1.0",
+        path: "/v1.0/identityProtection/riskyUsers/dismiss",
+        effect: "disruptive",
+        target,
+        payload: { userIds: [target] },
+    };
+}
+function parseSingleUser(raw, help) {
+    const user = String(raw ?? "").trim();
+    if (!user)
+        throw new AxiError("--user needs the risky-user ID to dismiss", "VALIDATION_ERROR", [help]);
+    if (user.includes(",")) {
+        throw new AxiError("--user takes exactly one risky-user ID; there is no bulk dismissal form", "VALIDATION_ERROR", [
+            help,
+            "Dismiss one user per command; each dismissal is its own audited intent",
+        ]);
+    }
+    return user;
+}
+async function readRiskState(session, profile, readOperation, user) {
+    const raw = await withGuidance(RISKY_USER_DENIAL_HINTS, () => session.execute({
+        profile,
+        operation: readOperation,
+        params: { "riskyUser-id": user },
+        query: { $select: RISK_STATE_SELECT },
+        ...(profile.mode === "application" ? {} : { scopes: [...RISKY_USER_DISMISS_READ_SCOPES] }),
+    }));
+    if (raw !== null && typeof raw === "object" && !Array.isArray(raw) && "id" in raw && typeof raw.id === "string" && raw.id.length > 0) {
+        const row = raw;
+        const id = raw.id;
+        return {
+            id,
+            userPrincipalName: row.userPrincipalName ?? null,
+            riskLevel: row.riskLevel ?? null,
+            riskState: row.riskState ?? null,
+            riskDetail: row.riskDetail ?? null,
+            riskLastUpdatedDateTime: row.riskLastUpdatedDateTime ?? null,
+        };
+    }
+    throw new AxiError("Graph returned a risky user without an object ID", "GRAPH_ERROR", [
+        "Read back the user with mg-axi entra risky-user show before attempting a dismissal",
+    ]);
+}
+function executeHint(user, profileName) {
+    const shell = (value) => /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+    return `mg-axi entra risky-user dismiss --user ${shell(user)} --execute`
+        + ` --confirm ${shell(user)}`
+        + ` --profile ${shell(profileName)}`;
+}
+function showHint(user, profileName) {
+    const shell = (value) => /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+    return `mg-axi entra risky-user show --id ${shell(user)} --profile ${shell(profileName)}`;
+}
+export async function dismissRiskyUser(args) {
+    const { session, coordinator, flags, profile, profileName, readOperation, help } = args;
+    const user = parseSingleUser(flags.user, help);
+    const version = String(flags["api-version"] ?? "v1.0");
+    if (version !== "v1.0") {
+        throw new AxiError(`--api-version ${version} cannot mutate: WRITE-05 binds POST /identityProtection/riskyUsers/dismiss to v1.0; beta writes stay blocked`, "VALIDATION_ERROR", [help]);
+    }
+    if (flags.scopes !== undefined) {
+        throw new AxiError("--scopes is not accepted: dismissal requests only the documented write scope", "VALIDATION_ERROR", [
+            help,
+            "Delegated dismissal requests IdentityRiskyUser.ReadWrite.All; application profiles use the configured Graph .default audience",
+        ]);
+    }
+    const requestedDefinition = riskDismissDefinition(user);
+    const execute = flags.execute === true;
+    // Gates first: preview refuses read-only, unscoped and beta-bound profiles
+    // before any read, credential or transport.
+    coordinator.preview(requestedDefinition);
+    if (execute) {
+        if (flags.confirm === undefined) {
+            throw new AxiError(`blocked: disruptive POST needs --confirm '${requestedDefinition.target}'`, "CONFIRM_REQUIRED", [`Re-run with --confirm '${requestedDefinition.target}'`]);
+        }
+        if (String(flags.confirm) !== requestedDefinition.target) {
+            throw new AxiError(`blocked: --confirm '${flags.confirm}' does not match target '${requestedDefinition.target}'`, "CONFIRM_MISMATCH", [`Re-run with --confirm '${requestedDefinition.target}'`]);
+        }
+    }
+    // The target is verified as a user through the READ-06 route: a failed or
+    // malformed read blocks the dismissal before anything is sent.
+    const state = await readRiskState(session, profile, readOperation, user);
+    const id = state.id;
+    const definition = { ...requestedDefinition, payload: { userIds: [id] } };
+    const preview = coordinator.preview(definition);
+    const dismissed = state.riskState === "dismissed";
+    const view = {
+        operation: definition.operation,
+        target: definition.target,
+        method: definition.method,
+        url: preview.url,
+        effect: definition.effect,
+        current: state,
+        desired: "dismissed",
+        noop: dismissed,
+    };
+    if (!execute) {
+        return {
+            preview: view,
+            help: [
+                dismissed
+                    ? "Already dismissed; no dismissal is needed"
+                    : executeHint(user, profileName),
+                ...(!dismissed
+                    ? ["Dismissing risk is disruptive: the --execute run needs the typed --confirm value shown above"]
+                    : []),
+                REMEDIATION_NOTE,
+                LICENCE_GUIDANCE,
+            ],
+        };
+    }
+    const result = await coordinator.execute(definition, {
+        execute: true,
+        confirm: String(flags.confirm),
+        ...(profile.mode === "application" ? {} : { scopes: [...RISKY_USER_DISMISS_WRITE_SCOPES] }),
+        readState: async () => (await readRiskState(session, profile, readOperation, id)).riskState,
+        isNoop: currentState => currentState === "dismissed",
+    });
+    if (result.kind === "failed") {
+        throw new AxiError(`Graph refused the risk dismissal (status ${result.status})`, "GRAPH_ERROR", [
+            ...(result.status === 403 ? [PERMISSION_GUIDANCE, ROLE_GUIDANCE, LICENCE_GUIDANCE] : []),
+            `Audit ${result.auditId} recorded the refusal; read back '${id}' and never replay this intent`,
+        ]);
+    }
+    if (result.kind === "unknown") {
+        throw new AxiError(`Dismissal of '${id}' 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 '${id}' with ${showHint(id, 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, dismissal: { user: { id, riskState: "dismissed" } } };
+    }
+    // Success carries no proof: dismissal answers 204 with an empty body, so
+    // only the reread decides between dismissed and conflict.
+    let verified = null;
+    try {
+        verified = await readRiskState(session, profile, readOperation, id);
+    }
+    catch (error) {
+        throw new AxiError(`Dismissal of '${user}' was sent (audit ${result.auditId}) but the verification read failed; the outcome is unknown`, "OUTCOME_UNKNOWN", [
+            ...(error instanceof AxiError ? error.suggestions : []),
+            `Read back '${id}' before doing anything else; never replay this intent`,
+        ]);
+    }
+    if (verified.riskState !== "dismissed") {
+        throw new AxiError(`Dismissal of '${user}' conflicts: the reread shows riskState ${JSON.stringify(verified.riskState)} instead of dismissed (audit ${result.auditId})`, "WRITE_CONFLICT", [`Read back '${id}' with ${showHint(id, profileName)} before doing anything else`, "Never replay this intent"]);
+    }
+    return { dismissal: { user: verified }, auditId: result.auditId };
+}