@knowttl/mg-axi 0.1.1 → 0.1.3

package/dist/entra-risk.js

@@ -1,18 +1,30 @@
 import { AxiError } from "axi-sdk-js";
+import { listTotals } from "./list-totals.js";
 // READ-06: the Entra risky-user and risk-detection read mapping behind
 // `mg-axi entra risky-user list/show` and `mg-axi entra risk-detection
-// list/show`. Operation construction stays beside its command; the shared
+// list/show`, extended with the workload-identity surface behind
+// `mg-axi entra risky-service-principal list/show`,
+// `mg-axi entra risky-service-principal history list/show` and
+// `mg-axi entra service-principal-risk-detection 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,
 // bounds detection queries in time, and projects rows for compact output.
 //
 // Reviewed against the v1.0 riskyuser-list/get and riskdetection-list/get
-// operation documentation on 2026-10-04. Risky-user reads take D/A
+// operation documentation on 2026-10-04, and against the v1.0
+// riskyserviceprincipal-list/get, history-list and
+// serviceprincipalriskdetection-list/get operation documentation on
+// 2026-10-06. Risky-user reads take D/A
 // IdentityRiskyUser.Read.All and risk-detection reads take D/A
-// IdentityRiskEvent.Read.All; delegated callers additionally need Global
+// IdentityRiskEvent.Read.All; risky-service-principal reads (including
+// history) take D/A IdentityRiskyServicePrincipal.Read.All while
+// service-principal risk detections reuse D/A IdentityRiskEvent.Read.All.
+// Delegated callers additionally need Global
 // Reader, Security Operator, Security Reader or Security Administrator. The
 // riskyUsers API requires a P2 licence, while risk detection permits P1 or
-// P2. Limited views stay limited: a premium detection without P2 detail
+// P2; the workload-identity APIs require a Microsoft Entra Workload
+// Identities Premium licence, and service-principal detections report
+// riskDetail and riskLevel hidden without it. Limited views stay limited: a premium detection without P2 detail
 // reports riskEventType generic, hidden risk levels report the licence
 // boundary instead of the level, and a null detection correlationId means no
 // sign-in is associated. None of these is ever reinterpreted as empty or
@@ -54,8 +66,67 @@ export const KNOWN_RISK_DETECTION_FIELDS = [
     "userPrincipalName",
     "additionalInfo",
 ];
+// Workload-identity surface. History items inherit every risky-service-
+// principal property and add the service-principal identifier plus the
+// actor/activity of the risk change. Service-principal detections carry the
+// service-principal join keys (servicePrincipalId, servicePrincipalDisplayName,
+// appId, keyIds) instead of user keys; keyIds are key-credential identifiers,
+// never secret material. tokenIssuerType stays absent for the same redaction
+// reason as above.
+export const KNOWN_RISKY_SP_FIELDS = [
+    "id",
+    "isEnabled",
+    "isProcessing",
+    "riskDetail",
+    "riskLastUpdatedDateTime",
+    "riskLevel",
+    "riskState",
+    "displayName",
+    "appId",
+    "servicePrincipalType",
+];
+export const KNOWN_RISKY_SP_HISTORY_FIELDS = [
+    "id",
+    "isEnabled",
+    "isProcessing",
+    "riskDetail",
+    "riskLastUpdatedDateTime",
+    "riskLevel",
+    "riskState",
+    "displayName",
+    "appId",
+    "servicePrincipalType",
+    "servicePrincipalId",
+    "initiatedBy",
+    "activity",
+];
+export const KNOWN_SP_DETECTION_FIELDS = [
+    "id",
+    "requestId",
+    "correlationId",
+    "riskEventType",
+    "riskState",
+    "riskLevel",
+    "riskDetail",
+    "source",
+    "detectionTimingType",
+    "activity",
+    "ipAddress",
+    "location",
+    "activityDateTime",
+    "detectedDateTime",
+    "lastUpdatedDateTime",
+    "servicePrincipalId",
+    "servicePrincipalDisplayName",
+    "appId",
+    "keyIds",
+    "additionalInfo",
+];
 const RISKY_USER_KNOWN = new Set(KNOWN_RISKY_USER_FIELDS);
 const RISK_DETECTION_KNOWN = new Set(KNOWN_RISK_DETECTION_FIELDS);
+const RISKY_SP_KNOWN = new Set(KNOWN_RISKY_SP_FIELDS);
+const RISKY_SP_HISTORY_KNOWN = new Set(KNOWN_RISKY_SP_HISTORY_FIELDS);
+const SP_DETECTION_KNOWN = new Set(KNOWN_SP_DETECTION_FIELDS);
 // Compact list rows: identifier, who is at risk, and the triage state.
 const DEFAULT_RISKY_USER_LIST_SELECT = ["id", "userPrincipalName", "riskLevel", "riskState"];
 const DEFAULT_RISK_DETECTION_LIST_SELECT = ["id", "detectedDateTime", "userPrincipalName", "riskLevel"];
@@ -64,6 +135,7 @@ const DEFAULT_RISKY_USER_SHOW_SELECT = [...KNOWN_RISKY_USER_FIELDS];
 const DEFAULT_RISK_DETECTION_SHOW_SELECT = [...KNOWN_RISK_DETECTION_FIELDS];
 export const DEFAULT_RISKY_USER_SCOPES = ["https://graph.microsoft.com/IdentityRiskyUser.Read.All"];
 export const DEFAULT_RISK_DETECTION_SCOPES = ["https://graph.microsoft.com/IdentityRiskEvent.Read.All"];
+export const DEFAULT_RISKY_SP_SCOPES = ["https://graph.microsoft.com/IdentityRiskyServicePrincipal.Read.All"];
 const TRUNCATE_AT = 500;
 function fieldList(raw, flag, known, knownList, help) {
     const parts = String(raw)
@@ -222,9 +294,27 @@ const RISK_DETECTION_DENIAL_HINTS = [
     "Risk-detection reads need IdentityRiskEvent.Read.All plus a supported directory role: Global Reader, Security Operator, Security Reader or Security Administrator for delegated access, or admin-consented IdentityRiskEvent.Read.All for application access",
     "Risk detection needs a P1 or P2 licence; premium detections report riskEventType generic without P2 detail, so generic is the server's limited view rather than the real type",
 ];
+const RISKY_SP_DENIAL_HINTS = [
+    "Risky-service-principal reads need IdentityRiskyServicePrincipal.Read.All plus a supported directory role: Global Reader, Security Operator, Security Reader or Security Administrator for delegated access, or admin-consented IdentityRiskyServicePrincipal.Read.All for application access",
+    "The riskyServicePrincipals API requires a Microsoft Entra Workload Identities Premium licence; data availability follows Entra retention policies",
+];
+const SP_DETECTION_DENIAL_HINTS = [
+    "Service-principal-risk-detection reads need IdentityRiskEvent.Read.All plus a supported directory role: Global Reader, Security Operator, Security Reader or Security Administrator for delegated access, or admin-consented IdentityRiskEvent.Read.All for application access",
+    "The servicePrincipalRiskDetection API requires a Microsoft Entra Workload Identities Premium licence; riskDetail and riskLevel report hidden without it, so hidden is the server's limited view rather than no risk",
+];
+// Nested history routes bind the parent risky-service-principal id before
+// credentials; a missing or empty parent fails as usage, never as Graph 404.
+function parentServicePrincipal(flags, help) {
+    const parent = flags["service-principal"];
+    if (parent === undefined || !String(parent).trim()) {
+        throw new AxiError("--service-principal needs the risky-service-principal object ID owning this history", "VALIDATION_ERROR", [help]);
+    }
+    return { "riskyServicePrincipal-id": String(parent) };
+}
 const RISKY_USER_LIST = {
     noun: "risky-user",
     key: "riskyUsers",
+    totalsNoun: "risky users",
     known: RISKY_USER_KNOWN,
     knownList: KNOWN_RISKY_USER_FIELDS,
     defaultSelect: DEFAULT_RISKY_USER_LIST_SELECT,
@@ -241,6 +331,7 @@ const RISKY_USER_LIST = {
 const RISK_DETECTION_LIST = {
     noun: "risk-detection",
     key: "riskDetections",
+    totalsNoun: "risk detections",
     dateField: "detectedDateTime",
     known: RISK_DETECTION_KNOWN,
     knownList: KNOWN_RISK_DETECTION_FIELDS,
@@ -257,6 +348,65 @@ const RISK_DETECTION_LIST = {
         "Limited views stay limited: riskEventType generic can hide a premium detection without P2 detail, and hidden risk levels report the licence boundary instead of the level - never read them as none",
     ],
 };
+// Compact workload rows: identifier, which workload, and the triage state.
+const DEFAULT_RISKY_SP_LIST_SELECT = ["id", "displayName", "riskLevel", "riskState"];
+const DEFAULT_SP_DETECTION_LIST_SELECT = ["id", "detectedDateTime", "servicePrincipalDisplayName", "riskLevel"];
+const DEFAULT_RISKY_SP_SHOW_SELECT = [...KNOWN_RISKY_SP_FIELDS];
+const DEFAULT_RISKY_SP_HISTORY_SHOW_SELECT = [...KNOWN_RISKY_SP_HISTORY_FIELDS];
+const DEFAULT_SP_DETECTION_SHOW_SELECT = [...KNOWN_SP_DETECTION_FIELDS];
+const RISKY_SP_LIST = {
+    noun: "risky-service-principal",
+    key: "riskyServicePrincipals",
+    totalsNoun: "risky service principals",
+    known: RISKY_SP_KNOWN,
+    knownList: KNOWN_RISKY_SP_FIELDS,
+    defaultSelect: DEFAULT_RISKY_SP_LIST_SELECT,
+    defaultScopes: DEFAULT_RISKY_SP_SCOPES,
+    denialHints: RISKY_SP_DENIAL_HINTS,
+    showHint: "mg-axi entra risky-service-principal show --id <risky-service-principal-id>",
+    emptyHints: profileName => [
+        `mg-axi entra risky-service-principal list --filter <odata-filter> ${profileHint(profileName)}`,
+        "0 risky service principals matched; the absence of results is the answer, not an error",
+        "Limited results stay limited: without Workload Identities Premium detail the service reports what the caller may see, so never read a short list as no risk",
+    ],
+    extraHelp: () => [],
+};
+const RISKY_SP_HISTORY_LIST = {
+    noun: "risky-service-principal history",
+    key: "riskyServicePrincipalHistory",
+    totalsNoun: "history items",
+    pathParams: parentServicePrincipal,
+    known: RISKY_SP_HISTORY_KNOWN,
+    knownList: KNOWN_RISKY_SP_HISTORY_FIELDS,
+    defaultSelect: DEFAULT_RISKY_SP_LIST_SELECT,
+    defaultScopes: DEFAULT_RISKY_SP_SCOPES,
+    denialHints: RISKY_SP_DENIAL_HINTS,
+    showHint: "mg-axi entra risky-service-principal history show --service-principal <risky-service-principal-id> --id <history-item-id>",
+    emptyHints: profileName => [
+        `mg-axi entra risky-service-principal history list --service-principal <risky-service-principal-id> ${profileHint(profileName)}`,
+        "0 history items matched; the absence of results is the answer, not an error",
+    ],
+    extraHelp: () => [],
+};
+const SP_DETECTION_LIST = {
+    noun: "service-principal-risk-detection",
+    key: "servicePrincipalRiskDetections",
+    totalsNoun: "service principal risk detections",
+    dateField: "detectedDateTime",
+    known: SP_DETECTION_KNOWN,
+    knownList: KNOWN_SP_DETECTION_FIELDS,
+    defaultSelect: DEFAULT_SP_DETECTION_LIST_SELECT,
+    defaultScopes: DEFAULT_RISK_DETECTION_SCOPES,
+    denialHints: SP_DETECTION_DENIAL_HINTS,
+    showHint: "mg-axi entra service-principal-risk-detection show --id <service-principal-risk-detection-id>",
+    emptyHints: profileName => [
+        `mg-axi entra service-principal-risk-detection list --since <earlier-iso-time> ${profileHint(profileName)}`,
+        "0 service-principal risk detections matched in this window; widen --since/--until or loosen --filter - the absence of results is the answer, not an error",
+    ],
+    extraHelp: () => [
+        "Limited views stay limited: riskDetail and riskLevel report hidden without Workload Identities Premium detail - never read hidden as none",
+    ],
+};
 async function listRisk(shape, session, flags, profile, operation, help, profileName) {
     const cursor = flags.cursor === undefined ? undefined : String(flags.cursor);
     if (cursor !== undefined && !cursor.trim())
@@ -292,6 +442,8 @@ async function listRisk(shape, session, flags, profile, operation, help, profile
         query.$filter = String(flags.filter);
     }
     const args = { profile, operation, query, scopes };
+    if (shape.pathParams !== undefined)
+        args.params = shape.pathParams(flags, help);
     if (cursor !== undefined)
         args.cursor = cursor;
     if (flags.all === true) {
@@ -322,16 +474,17 @@ async function listRisk(shape, session, flags, profile, operation, help, profile
     if (!result.complete) {
         return {
             [shape.key]: rows,
-            count: { returned: rows.length, complete: false, reason: result.reason },
+            ...listTotals(rows.length, result.total, shape.totalsNoun, false),
+            complete: false,
+            reason: result.reason,
             cursor: result.cursor,
             help: [...truncationHints, `Resume losslessly with the same flags plus --cursor - ${profileHint(profileName)} and supply the returned cursor on stdin`, showHint, ...shape.extraHelp(profileName)],
         };
     }
-    const count = { returned: rows.length, complete: true };
     if (!rows.length) {
-        return { [shape.key]: rows, count, help: shape.emptyHints(profileName) };
+        return { [shape.key]: rows, ...listTotals(rows.length, result.total, shape.totalsNoun, true), complete: true, help: shape.emptyHints(profileName) };
     }
-    return { [shape.key]: rows, count, help: [...truncationHints, showHint, ...shape.extraHelp(profileName)] };
+    return { [shape.key]: rows, ...listTotals(rows.length, result.total, shape.totalsNoun, true), complete: true, help: [...truncationHints, showHint, ...shape.extraHelp(profileName)] };
 }
 const RISKY_USER_SHOW = {
     noun: "risky-user",
@@ -363,6 +516,50 @@ const RISK_DETECTION_SHOW = {
     ],
     noSignInNote: "This detection carries no associated sign-in (correlationId is null); sign-in correlation does not apply",
 };
+const RISKY_SP_SHOW = {
+    noun: "risky-service-principal",
+    key: "riskyServicePrincipal",
+    param: "riskyServicePrincipal-id",
+    known: RISKY_SP_KNOWN,
+    knownList: KNOWN_RISKY_SP_FIELDS,
+    defaultSelect: DEFAULT_RISKY_SP_SHOW_SELECT,
+    defaultScopes: DEFAULT_RISKY_SP_SCOPES,
+    denialHints: RISKY_SP_DENIAL_HINTS,
+    correlationHelp: profileName => [
+        `List this workload's detections with mg-axi entra service-principal-risk-detection list --since <iso-time> --filter "servicePrincipalId eq '<risky-service-principal-id>'" ${profileHint(profileName)}`,
+        `List this workload's risk history with mg-axi entra risky-service-principal history list --service-principal <risky-service-principal-id> ${profileHint(profileName)}`,
+        "Confirming compromise and dismissing risk are separately reviewed writes; this read never confirms, dismisses or remediates risk",
+    ],
+};
+const RISKY_SP_HISTORY_SHOW = {
+    noun: "risky-service-principal history",
+    key: "riskyServicePrincipalHistoryItem",
+    param: "riskyServicePrincipalHistoryItem-id",
+    parentParams: parentServicePrincipal,
+    known: RISKY_SP_HISTORY_KNOWN,
+    knownList: KNOWN_RISKY_SP_HISTORY_FIELDS,
+    defaultSelect: DEFAULT_RISKY_SP_HISTORY_SHOW_SELECT,
+    defaultScopes: DEFAULT_RISKY_SP_SCOPES,
+    denialHints: RISKY_SP_DENIAL_HINTS,
+    correlationHelp: profileName => [
+        `List this workload's detections with mg-axi entra service-principal-risk-detection list --since <iso-time> --filter "servicePrincipalId eq '<risky-service-principal-id>'" ${profileHint(profileName)}`,
+    ],
+};
+const SP_DETECTION_SHOW = {
+    noun: "service-principal-risk-detection",
+    key: "servicePrincipalRiskDetection",
+    param: "servicePrincipalRiskDetection-id",
+    known: SP_DETECTION_KNOWN,
+    knownList: KNOWN_SP_DETECTION_FIELDS,
+    defaultSelect: DEFAULT_SP_DETECTION_SHOW_SELECT,
+    defaultScopes: DEFAULT_RISK_DETECTION_SCOPES,
+    denialHints: SP_DETECTION_DENIAL_HINTS,
+    correlationHelp: profileName => [
+        `List this workload's detections with mg-axi entra service-principal-risk-detection list --since <iso-time> --filter "servicePrincipalId eq '<service-principal-id>'" ${profileHint(profileName)}`,
+        "Limited views stay limited: riskDetail and riskLevel report hidden without Workload Identities Premium detail - never read hidden as none",
+    ],
+    noSignInNote: "This detection carries no associated sign-in (correlationId is null); sign-in correlation does not apply",
+};
 async function showRisk(shape, session, flags, profile, operation, help, profileName) {
     const { select, fields } = selectedFields(flags, shape.defaultSelect, shape.known, shape.knownList, help);
     const scopes = scopesFor(flags, profile, shape.defaultScopes, help);
@@ -370,7 +567,7 @@ async function showRisk(shape, session, flags, profile, operation, help, profile
     const raw = await withGuidance(shape.denialHints, () => session.execute({
         profile,
         operation,
-        params: { [shape.param]: String(flags.id) },
+        params: { ...(shape.parentParams === undefined ? {} : shape.parentParams(flags, help)), [shape.param]: String(flags.id) },
         query: { $select: select.join(",") },
         scopes,
     }));
@@ -402,3 +599,21 @@ export async function listRiskDetections(session, flags, profile, operation, hel
 export async function showRiskDetection(session, flags, profile, operation, help, profileName) {
     return showRisk(RISK_DETECTION_SHOW, session, flags, profile, operation, help, profileName);
 }
+export async function listRiskyServicePrincipals(session, flags, profile, operation, help, profileName) {
+    return listRisk(RISKY_SP_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showRiskyServicePrincipal(session, flags, profile, operation, help, profileName) {
+    return showRisk(RISKY_SP_SHOW, session, flags, profile, operation, help, profileName);
+}
+export async function listRiskyServicePrincipalHistory(session, flags, profile, operation, help, profileName) {
+    return listRisk(RISKY_SP_HISTORY_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showRiskyServicePrincipalHistory(session, flags, profile, operation, help, profileName) {
+    return showRisk(RISKY_SP_HISTORY_SHOW, session, flags, profile, operation, help, profileName);
+}
+export async function listServicePrincipalRiskDetections(session, flags, profile, operation, help, profileName) {
+    return listRisk(SP_DETECTION_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showServicePrincipalRiskDetection(session, flags, profile, operation, help, profileName) {
+    return showRisk(SP_DETECTION_SHOW, session, flags, profile, operation, help, profileName);
+}

package/dist/entra-roles.js

@@ -1,26 +1,41 @@
 import { AxiError } from "axi-sdk-js";
+import { listTotals } from "./list-totals.js";
 // READ-09: the Entra directory-role and PIM read mapping behind
-// `mg-axi entra directory-role list/show`, `mg-axi entra role-assignment
-// list`, `mg-axi entra pim eligible list` and `mg-axi entra pim active list`.
+// `mg-axi entra directory-role list/show`, `mg-axi entra directory-role-template
+// list/show`, `mg-axi entra directory-role member list`, `mg-axi entra
+// directory-role scoped-member list/show`, `mg-axi entra scoped-role-membership
+// list/show`, `mg-axi entra role-assignment list`, `mg-axi entra pim eligible
+// list` and `mg-axi entra pim active list`.
 // 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 directoryrole-list, directoryrole-get,
+// directoryroletemplate-list, directoryroletemplate-get,
+// directoryrole-list-members, directoryrole-list-scopedmembers,
+// scopedrolemembership-list, scopedrolemembership-get,
 // rbacapplication-list-roleassignments,
 // rbacapplication-list-roleeligibilityscheduleinstances and
 // rbacapplication-list-roleassignmentscheduleinstances operation
-// documentation on 2026-10-04. Directory-role reads and role
-// assignments read D/A RoleManagement.Read.Directory; eligible PIM reads
+// documentation on 2026-10-04 (roles, assignments and PIM) and 2026-10-06
+// (templates, members, scoped members and scoped memberships). Directory-role reads, role
+// assignments, templates, members, scoped members and scoped memberships
+// read D/A RoleManagement.Read.Directory; eligible PIM reads
 // D/A RoleEligibilitySchedule.Read.Directory; active PIM reads D/A
 // RoleAssignmentSchedule.Read.Directory. Delegated callers additionally need
 // a supported administrator role per operation. None of these collections
 // documents an advanced-query contract, so --filter passes through as plain
 // $filter with no $count or ConsistencyLevel attached.
 //
-// The four views cover: directoryRoles are activated role
+// The views cover: directoryRoles are activated role
 // instances only (a role appears here after activation, never before);
+// directoryRoleTemplates describe every role definition whether activated or
+// not; members are the principals assigned to one activated role (@odata.type
+// names each member kind: user, group, device or service principal); scoped
+// members bind one role to one principal within one directory scope;
+// scopedRoleMemberships are the administrative-unit-scoped admin assignments
+// (directory-wide assignments live on roleAssignments);
 // roleAssignments include direct and PIM-activated assignments; eligible schedule
 // instances are PIM-eligible but not active; active schedule instances cover
 // both directly assigned (assignmentType Assigned) and activated eligible
@@ -56,10 +71,31 @@ export const KNOWN_ELIGIBLE_FIELDS = [
     "endDateTime",
 ];
 export const KNOWN_ACTIVE_FIELDS = [...KNOWN_ELIGIBLE_FIELDS, "assignmentType"];
+export const KNOWN_TEMPLATE_FIELDS = [
+    "id",
+    "displayName",
+    "description",
+];
+export const KNOWN_ROLE_MEMBER_FIELDS = [
+    "id",
+    "displayName",
+    "mail",
+    "userPrincipalName",
+];
+export const KNOWN_SCOPED_MEMBER_FIELDS = [
+    "id",
+    "principalId",
+    "roleId",
+    "directoryScopeId",
+    "administrativeUnitId",
+];
 const ROLE_KNOWN = new Set(KNOWN_ROLE_FIELDS);
 const ASSIGNMENT_KNOWN = new Set(KNOWN_ASSIGNMENT_FIELDS);
 const ELIGIBLE_KNOWN = new Set(KNOWN_ELIGIBLE_FIELDS);
 const ACTIVE_KNOWN = new Set(KNOWN_ACTIVE_FIELDS);
+const TEMPLATE_KNOWN = new Set(KNOWN_TEMPLATE_FIELDS);
+const MEMBER_KNOWN = new Set(KNOWN_ROLE_MEMBER_FIELDS);
+const SCOPED_KNOWN = new Set(KNOWN_SCOPED_MEMBER_FIELDS);
 // Compact rows: identifiers plus the correlation keys. For built-in roles
 // the unified roleDefinitionId matches the directory-role roleTemplateId.
 const DEFAULT_ROLE_LIST_SELECT = ["id", "displayName", "description", "roleTemplateId"];
@@ -67,6 +103,11 @@ const DEFAULT_ROLE_SHOW_SELECT = [...KNOWN_ROLE_FIELDS];
 const DEFAULT_ASSIGNMENT_SELECT = ["id", "principalId", "roleDefinitionId", "directoryScopeId"];
 const DEFAULT_ELIGIBLE_SELECT = ["id", "principalId", "roleDefinitionId", "memberType"];
 const DEFAULT_ACTIVE_SELECT = ["id", "principalId", "roleDefinitionId", "assignmentType", "memberType"];
+const DEFAULT_TEMPLATE_LIST_SELECT = ["id", "displayName", "description"];
+const DEFAULT_TEMPLATE_SHOW_SELECT = [...KNOWN_TEMPLATE_FIELDS];
+const DEFAULT_MEMBER_SELECT = ["id", "displayName"];
+const DEFAULT_SCOPED_LIST_SELECT = ["id", "principalId", "roleId", "directoryScopeId"];
+const DEFAULT_SCOPED_SHOW_SELECT = [...KNOWN_SCOPED_MEMBER_FIELDS];
 export const DEFAULT_ROLE_SCOPES = ["https://graph.microsoft.com/RoleManagement.Read.Directory"];
 export const DEFAULT_ELIGIBLE_SCOPES = ["https://graph.microsoft.com/RoleEligibilitySchedule.Read.Directory"];
 export const DEFAULT_ACTIVE_SCOPES = ["https://graph.microsoft.com/RoleAssignmentSchedule.Read.Directory"];
@@ -114,9 +155,14 @@ function truncateValue(value, full) {
 }
 // Local projection preserves Graph's null/missing distinction: an explicit
 // null stays null, an absent property stays absent and is never synthesized.
-function project(row, fields, full) {
+function project(row, fields, full, keepODataType = false) {
     const source = row !== null && typeof row === "object" && !Array.isArray(row) ? row : {};
     const projected = {};
+    // Heterogeneous member rows carry their kind in @odata.type, which is
+    // structural rather than a selectable property, so it rides along first.
+    if (keepODataType && typeof source["@odata.type"] === "string") {
+        projected["@odata.type"] = source["@odata.type"];
+    }
     let truncated = false;
     for (const field of fields) {
         if (!Object.hasOwn(source, field))
@@ -174,9 +220,14 @@ const ACTIVE_DENIAL_HINTS = [
     "Active PIM reads need RoleAssignmentSchedule.Read.Directory plus Global Reader, Security Operator, Security Reader, Security Administrator or Privileged Role Administrator for delegated access, or admin-consented RoleAssignmentSchedule.Read.Directory for application access",
     "PIM reads need P2 or ID Governance, not only P2",
 ];
+const SCOPED_DENIAL_HINTS = [
+    "Scoped membership reads need RoleManagement.Read.Directory plus Global Reader, Security Reader or Privileged Role Administrator for delegated access, or admin-consented RoleManagement.Read.Directory for application access",
+    "Administrative-unit-scoped memberships need P1",
+];
 const ROLE_LIST = {
     command: "entra directory-role list",
     key: "directoryRoles",
+    noun: "directory roles",
     known: ROLE_KNOWN,
     knownList: KNOWN_ROLE_FIELDS,
     defaultSelect: DEFAULT_ROLE_LIST_SELECT,
@@ -188,6 +239,7 @@ const ROLE_LIST = {
 const ASSIGNMENT_LIST = {
     command: "entra role-assignment list",
     key: "roleAssignments",
+    noun: "role assignments",
     known: ASSIGNMENT_KNOWN,
     knownList: KNOWN_ASSIGNMENT_FIELDS,
     defaultSelect: DEFAULT_ASSIGNMENT_SELECT,
@@ -199,6 +251,7 @@ const ASSIGNMENT_LIST = {
 const PIM_ELIGIBLE = {
     command: "entra pim eligible list",
     key: "eligibleAssignments",
+    noun: "eligible assignments",
     known: ELIGIBLE_KNOWN,
     knownList: KNOWN_ELIGIBLE_FIELDS,
     defaultSelect: DEFAULT_ELIGIBLE_SELECT,
@@ -210,6 +263,7 @@ const PIM_ELIGIBLE = {
 const PIM_ACTIVE = {
     command: "entra pim active list",
     key: "activeAssignments",
+    noun: "active assignments",
     known: ACTIVE_KNOWN,
     knownList: KNOWN_ACTIVE_FIELDS,
     defaultSelect: DEFAULT_ACTIVE_SELECT,
@@ -218,10 +272,68 @@ const PIM_ACTIVE = {
     scopeNote: "Active distinguishes directly assigned (assignmentType Assigned) and activated eligible (assignmentType Activated) assignments",
     emptyNote: "0 active assignments matched; the absence of results is the answer, not an error",
 };
+const TEMPLATE_LIST = {
+    command: "entra directory-role-template list",
+    key: "directoryRoleTemplates",
+    noun: "directory-role templates",
+    known: TEMPLATE_KNOWN,
+    knownList: KNOWN_TEMPLATE_FIELDS,
+    defaultSelect: DEFAULT_TEMPLATE_LIST_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: ROLE_DENIAL_HINTS,
+    scopeNote: "Templates describe every role definition; activation state lives on directoryRoles, which appear only after activation",
+    emptyNote: "0 directory-role templates matched; the absence of results is the answer, not an error",
+};
+const MEMBER_LIST = {
+    command: "entra directory-role member list",
+    key: "roleMembers",
+    noun: "role members",
+    known: MEMBER_KNOWN,
+    knownList: KNOWN_ROLE_MEMBER_FIELDS,
+    defaultSelect: DEFAULT_MEMBER_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: ROLE_DENIAL_HINTS,
+    scopeNote: "Members are the principals assigned to the activated role; @odata.type names each member kind (user, group, device or service principal)",
+    emptyNote: "0 role members matched; the absence of results is the answer, not an error",
+    parent: { param: "directoryRole-id", flag: "role", label: "activated directory-role object ID whose members are listed" },
+    keepODataType: true,
+};
+const SCOPED_LIST = {
+    command: "entra directory-role scoped-member list",
+    key: "scopedMembers",
+    noun: "scoped members",
+    known: SCOPED_KNOWN,
+    knownList: KNOWN_SCOPED_MEMBER_FIELDS,
+    defaultSelect: DEFAULT_SCOPED_LIST_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: SCOPED_DENIAL_HINTS,
+    scopeNote: "Scoped members bind one role to one principal within one directory scope; administrative-unit scopes need P1",
+    emptyNote: "0 scoped members matched; the absence of results is the answer, not an error",
+    parent: { param: "directoryRole-id", flag: "role", label: "activated directory-role object ID whose scoped members are listed" },
+};
+const MEMBERSHIP_LIST = {
+    command: "entra scoped-role-membership list",
+    key: "scopedRoleMemberships",
+    noun: "scoped role memberships",
+    known: SCOPED_KNOWN,
+    knownList: KNOWN_SCOPED_MEMBER_FIELDS,
+    defaultSelect: DEFAULT_SCOPED_LIST_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: SCOPED_DENIAL_HINTS,
+    scopeNote: "Scoped role memberships are administrative-unit-scoped admin assignments; directory-wide assignments live on roleAssignments",
+    emptyNote: "0 scoped role memberships matched; the absence of results is the answer, not an error",
+};
 async function listCollection(shape, session, flags, profile, operation, help, profileName) {
     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]);
+    let params;
+    if (shape.parent !== undefined) {
+        const parentId = String(flags[shape.parent.flag] ?? "");
+        if (!parentId.trim())
+            throw new AxiError(`--${shape.parent.flag} needs the ${shape.parent.label}`, "VALIDATION_ERROR", [help]);
+        params = { [shape.parent.param]: parentId };
+    }
     const saved = cursor === undefined ? undefined : session.cursorQuery(operation, cursor);
     const savedSelect = saved?.$select;
     const { select, fields } = selectedFields(flags, savedSelect === undefined ? shape.defaultSelect : fieldList(savedSelect, "select", shape.known, shape.knownList, help), shape.known, shape.knownList, help);
@@ -235,6 +347,8 @@ async function listCollection(shape, session, flags, profile, operation, help, p
     if (filter !== undefined)
         query.$filter = filter;
     const args = { profile, operation, query, scopes };
+    if (params !== undefined)
+        args.params = params;
     if (cursor !== undefined)
         args.cursor = cursor;
     if (flags.all === true) {
@@ -251,11 +365,13 @@ async function listCollection(shape, session, flags, profile, operation, help, p
     const rows = [];
     let truncated = false;
     for (const row of result.value) {
-        const projected = project(row, fields, full);
+        const projected = project(row, fields, full, shape.keepODataType === true);
         rows.push(projected.row);
         truncated = truncated || projected.truncated;
     }
-    const showHint = shape.key === "directoryRoles" ? `mg-axi entra directory-role show --id <role-id> ${profileHint(profileName)}` : undefined;
+    const showHint = shape.key === "directoryRoles" ? `mg-axi entra directory-role show --id <role-id> ${profileHint(profileName)}`
+        : shape.key === "directoryRoleTemplates" ? `mg-axi entra directory-role-template show --id <template-id> ${profileHint(profileName)}`
+            : undefined;
     const correlateHint = shape.key === "directoryRoles"
         ? undefined
         : `For built-in roles, roleDefinitionId matches the directory-role roleTemplateId: mg-axi entra directory-role list ${profileHint(profileName)}`;
@@ -264,16 +380,17 @@ async function listCollection(shape, session, flags, profile, operation, help, p
     if (!result.complete) {
         return {
             [shape.key]: rows,
-            count: { returned: rows.length, complete: false, reason: result.reason },
+            ...listTotals(rows.length, result.total, shape.noun, false),
+            complete: false,
+            reason: result.reason,
             cursor: result.cursor,
             help: [...truncationHints, `Resume losslessly with the same flags plus --cursor <cursor-from-output> ${profileHint(profileName)}`, ...standing],
         };
     }
-    const count = { returned: rows.length, complete: true };
     if (!rows.length) {
-        return { [shape.key]: rows, count, help: [shape.emptyNote, ...standing] };
+        return { [shape.key]: rows, ...listTotals(rows.length, result.total, shape.noun, true), complete: true, help: [shape.emptyNote, ...standing] };
     }
-    return { [shape.key]: rows, count, help: [...truncationHints, ...standing] };
+    return { [shape.key]: rows, ...listTotals(rows.length, result.total, shape.noun, true), complete: true, help: [...truncationHints, ...standing] };
 }
 export async function listDirectoryRoles(session, flags, profile, operation, help, profileName) {
     return listCollection(ROLE_LIST, session, flags, profile, operation, help, profileName);
@@ -308,3 +425,78 @@ export async function listPimEligible(session, flags, profile, operation, help,
 export async function listPimActive(session, flags, profile, operation, help, profileName) {
     return listCollection(PIM_ACTIVE, session, flags, profile, operation, help, profileName);
 }
+const TEMPLATE_SINGLE = {
+    command: "entra directory-role-template show",
+    key: "directoryRoleTemplate",
+    noun: "directory-role template",
+    known: TEMPLATE_KNOWN,
+    knownList: KNOWN_TEMPLATE_FIELDS,
+    defaultSelect: DEFAULT_TEMPLATE_SHOW_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: ROLE_DENIAL_HINTS,
+};
+const SCOPED_SINGLE = {
+    command: "entra directory-role scoped-member show",
+    key: "scopedMember",
+    noun: "scoped member",
+    known: SCOPED_KNOWN,
+    knownList: KNOWN_SCOPED_MEMBER_FIELDS,
+    defaultSelect: DEFAULT_SCOPED_SHOW_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: SCOPED_DENIAL_HINTS,
+};
+const MEMBERSHIP_SINGLE = {
+    command: "entra scoped-role-membership show",
+    key: "scopedRoleMembership",
+    noun: "scoped role membership",
+    known: SCOPED_KNOWN,
+    knownList: KNOWN_SCOPED_MEMBER_FIELDS,
+    defaultSelect: DEFAULT_SCOPED_SHOW_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: SCOPED_DENIAL_HINTS,
+};
+async function showSingle(shape, params, session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, shape.defaultSelect, shape.known, shape.knownList, help);
+    const scopes = scopesFor(flags, profile, shape.defaultScopes, help);
+    const full = flags.full === true;
+    const raw = await withGuidance(shape.denialHints, () => session.execute({
+        profile,
+        operation,
+        params,
+        query: { $select: select.join(",") },
+        scopes,
+    }));
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new AxiError(`Graph returned a malformed ${shape.noun} body`, "GRAPH_ERROR", [
+            `Single-${shape.noun} reads carry one object; treat anything else as unknown, not empty`,
+        ]);
+    }
+    const { row, truncated } = project(raw, fields, full);
+    if (truncated)
+        return { [shape.key]: row, help: [fullHint(shape.command, flags, profileName)] };
+    return { [shape.key]: row };
+}
+export async function listDirectoryRoleTemplates(session, flags, profile, operation, help, profileName) {
+    return listCollection(TEMPLATE_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showDirectoryRoleTemplate(session, flags, profile, operation, help, profileName) {
+    return showSingle(TEMPLATE_SINGLE, { "directoryRoleTemplate-id": String(flags.id) }, session, flags, profile, operation, help, profileName);
+}
+export async function listRoleMembers(session, flags, profile, operation, help, profileName) {
+    return listCollection(MEMBER_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function listScopedMembers(session, flags, profile, operation, help, profileName) {
+    return listCollection(SCOPED_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showScopedMember(session, flags, profile, operation, help, profileName) {
+    const roleId = String(flags.role ?? "");
+    if (!roleId.trim())
+        throw new AxiError("--role needs the activated directory-role object ID owning the scoped member", "VALIDATION_ERROR", [help]);
+    return showSingle(SCOPED_SINGLE, { "directoryRole-id": roleId, "scopedRoleMembership-id": String(flags.id) }, session, flags, profile, operation, help, profileName);
+}
+export async function listScopedRoleMemberships(session, flags, profile, operation, help, profileName) {
+    return listCollection(MEMBERSHIP_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showScopedRoleMembership(session, flags, profile, operation, help, profileName) {
+    return showSingle(MEMBERSHIP_SINGLE, { "scopedRoleMembership-id": String(flags.id) }, session, flags, profile, operation, help, profileName);
+}