@pnp/cli-microsoft365 10.0.0-beta.48e9f7d → 10.0.0-beta.787c5f1

package/dist/utils/entraApp.js

@@ -0,0 +1,283 @@
+import fs from 'fs';
+import request from '../request.js';
+import { odata } from './odata.js';
+async function getCertificateBase64Encoded({ options, logger, debug }) {
+    if (options.certificateBase64Encoded) {
+        return options.certificateBase64Encoded;
+    }
+    if (debug) {
+        await logger.logToStderr(`Reading existing ${options.certificateFile}...`);
+    }
+    try {
+        return fs.readFileSync(options.certificateFile, { encoding: 'base64' });
+    }
+    catch (e) {
+        throw new Error(`Error reading certificate file: ${e}. Please add the certificate using base64 option '--certificateBase64Encoded'.`);
+    }
+}
+async function createServicePrincipal(appId) {
+    const requestOptions = {
+        url: `https://graph.microsoft.com/v1.0/myorganization/servicePrincipals`,
+        headers: {
+            'content-type': 'application/json'
+        },
+        data: {
+            appId: appId
+        },
+        responseType: 'json'
+    };
+    return request.post(requestOptions);
+}
+async function grantOAuth2Permission({ appId, resourceId, scopeName }) {
+    const grantAdminConsentApplicationRequestOptions = {
+        url: `https://graph.microsoft.com/v1.0/myorganization/oauth2PermissionGrants`,
+        headers: {
+            accept: 'application/json;odata.metadata=none'
+        },
+        responseType: 'json',
+        data: {
+            clientId: appId,
+            consentType: "AllPrincipals",
+            principalId: null,
+            resourceId: resourceId,
+            scope: scopeName
+        }
+    };
+    return request.post(grantAdminConsentApplicationRequestOptions);
+}
+async function addRoleToServicePrincipal({ objectId, resourceId, appRoleId }) {
+    const requestOptions = {
+        url: `https://graph.microsoft.com/v1.0/myorganization/servicePrincipals/${objectId}/appRoleAssignments`,
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        responseType: 'json',
+        data: {
+            appRoleId: appRoleId,
+            principalId: objectId,
+            resourceId: resourceId
+        }
+    };
+    return request.post(requestOptions);
+}
+async function getRequiredResourceAccessForApis({ servicePrincipals, apis, scopeType, logger, debug }) {
+    if (!apis) {
+        return [];
+    }
+    const resolvedApis = [];
+    const requestedApis = apis.split(',').map(a => a.trim());
+    for (const api of requestedApis) {
+        const pos = api.lastIndexOf('/');
+        const permissionName = api.substring(pos + 1);
+        const servicePrincipalName = api.substring(0, pos);
+        if (debug) {
+            await logger.logToStderr(`Resolving ${api}...`);
+            await logger.logToStderr(`Permission name: ${permissionName}`);
+            await logger.logToStderr(`Service principal name: ${servicePrincipalName}`);
+        }
+        const servicePrincipal = servicePrincipals.find(sp => (sp.servicePrincipalNames.indexOf(servicePrincipalName) > -1 ||
+            sp.servicePrincipalNames.indexOf(`${servicePrincipalName}/`) > -1));
+        if (!servicePrincipal) {
+            throw `Service principal ${servicePrincipalName} not found`;
+        }
+        const scopesOfType = scopeType === 'Scope' ? servicePrincipal.oauth2PermissionScopes : servicePrincipal.appRoles;
+        const permission = scopesOfType.find(scope => scope.value === permissionName);
+        if (!permission) {
+            throw `Permission ${permissionName} for service principal ${servicePrincipalName} not found`;
+        }
+        let resolvedApi = resolvedApis.find(a => a.resourceAppId === servicePrincipal.appId);
+        if (!resolvedApi) {
+            resolvedApi = {
+                resourceAppId: servicePrincipal.appId,
+                resourceAccess: []
+            };
+            resolvedApis.push(resolvedApi);
+        }
+        const resourceAccessPermission = {
+            id: permission.id,
+            type: scopeType
+        };
+        resolvedApi.resourceAccess.push(resourceAccessPermission);
+        updateAppPermissions({
+            spId: servicePrincipal.id,
+            resourceAccessPermission,
+            oAuth2PermissionValue: permission.value
+        });
+    }
+    return resolvedApis;
+}
+function updateAppPermissions({ spId, resourceAccessPermission, oAuth2PermissionValue }) {
+    // During API resolution, we store globally both app role assignments and oauth2permissions
+    // So that we'll be able to parse them during the admin consent process
+    let existingPermission = entraApp.appPermissions.find(oauth => oauth.resourceId === spId);
+    if (!existingPermission) {
+        existingPermission = {
+            resourceId: spId,
+            resourceAccess: [],
+            scope: []
+        };
+        entraApp.appPermissions.push(existingPermission);
+    }
+    if (resourceAccessPermission.type === 'Scope' && oAuth2PermissionValue && !existingPermission.scope.find(scp => scp === oAuth2PermissionValue)) {
+        existingPermission.scope.push(oAuth2PermissionValue);
+    }
+    if (!existingPermission.resourceAccess.find(res => res.id === resourceAccessPermission.id)) {
+        existingPermission.resourceAccess.push(resourceAccessPermission);
+    }
+}
+export const entraApp = {
+    appPermissions: [],
+    createAppRegistration: async ({ options, apis, logger, verbose, debug }) => {
+        const applicationInfo = {
+            displayName: options.name,
+            signInAudience: options.multitenant ? 'AzureADMultipleOrgs' : 'AzureADMyOrg'
+        };
+        if (apis.length > 0) {
+            applicationInfo.requiredResourceAccess = apis;
+        }
+        if (options.redirectUris) {
+            applicationInfo[options.platform] = {
+                redirectUris: options.redirectUris.split(',').map(u => u.trim())
+            };
+        }
+        if (options.implicitFlow) {
+            if (!applicationInfo.web) {
+                applicationInfo.web = {};
+            }
+            applicationInfo.web.implicitGrantSettings = {
+                enableAccessTokenIssuance: true,
+                enableIdTokenIssuance: true
+            };
+        }
+        if (options.certificateFile || options.certificateBase64Encoded) {
+            const certificateBase64Encoded = await getCertificateBase64Encoded({ options, logger, debug });
+            const newKeyCredential = {
+                type: 'AsymmetricX509Cert',
+                usage: 'Verify',
+                displayName: options.certificateDisplayName,
+                key: certificateBase64Encoded
+            };
+            applicationInfo.keyCredentials = [newKeyCredential];
+        }
+        if (options.allowPublicClientFlows) {
+            applicationInfo.isFallbackPublicClient = true;
+        }
+        if (verbose) {
+            await logger.logToStderr(`Creating Microsoft Entra app registration...`);
+        }
+        const createApplicationRequestOptions = {
+            url: `https://graph.microsoft.com/v1.0/myorganization/applications`,
+            headers: {
+                accept: 'application/json;odata.metadata=none'
+            },
+            responseType: 'json',
+            data: applicationInfo
+        };
+        return request.post(createApplicationRequestOptions);
+    },
+    grantAdminConsent: async ({ appInfo, appPermissions, adminConsent, logger, debug }) => {
+        if (!adminConsent || appPermissions.length === 0) {
+            return appInfo;
+        }
+        const sp = await createServicePrincipal(appInfo.appId);
+        if (debug) {
+            await logger.logToStderr("Service principal created, returned object id: " + sp.id);
+        }
+        const tasks = [];
+        appPermissions.forEach(async (permission) => {
+            if (permission.scope.length > 0) {
+                tasks.push(grantOAuth2Permission({
+                    appId: sp.id,
+                    resourceId: permission.resourceId,
+                    scopeName: permission.scope.join(' ')
+                }));
+                if (debug) {
+                    await logger.logToStderr(`Admin consent granted for following resource ${permission.resourceId}, with delegated permissions: ${permission.scope.join(',')}`);
+                }
+            }
+            permission.resourceAccess.filter(access => access.type === "Role").forEach(async (access) => {
+                tasks.push(addRoleToServicePrincipal({
+                    objectId: sp.id,
+                    resourceId: permission.resourceId,
+                    appRoleId: access.id
+                }));
+                if (debug) {
+                    await logger.logToStderr(`Admin consent granted for following resource ${permission.resourceId}, with application permission: ${access.id}`);
+                }
+            });
+        });
+        await Promise.all(tasks);
+        return appInfo;
+    },
+    resolveApis: async ({ options, manifest, logger, verbose, debug }) => {
+        if (!options.apisDelegated && !options.apisApplication
+            && (typeof manifest?.requiredResourceAccess === 'undefined' || manifest.requiredResourceAccess.length === 0)) {
+            return [];
+        }
+        if (verbose) {
+            await logger.logToStderr('Resolving requested APIs...');
+        }
+        const servicePrincipals = await odata.getAllItems(`https://graph.microsoft.com/v1.0/myorganization/servicePrincipals?$select=appId,appRoles,id,oauth2PermissionScopes,servicePrincipalNames`);
+        let resolvedApis = [];
+        if (options.apisDelegated || options.apisApplication) {
+            resolvedApis = await getRequiredResourceAccessForApis({
+                servicePrincipals,
+                apis: options.apisDelegated,
+                scopeType: 'Scope',
+                logger,
+                debug
+            });
+            if (verbose) {
+                await logger.logToStderr(`Resolved delegated permissions: ${JSON.stringify(resolvedApis, null, 2)}`);
+            }
+            const resolvedApplicationApis = await getRequiredResourceAccessForApis({
+                servicePrincipals,
+                apis: options.apisApplication,
+                scopeType: 'Role',
+                logger,
+                debug
+            });
+            if (verbose) {
+                await logger.logToStderr(`Resolved application permissions: ${JSON.stringify(resolvedApplicationApis, null, 2)}`);
+            }
+            // merge resolved application APIs onto resolved delegated APIs
+            resolvedApplicationApis.forEach(resolvedRequiredResource => {
+                const requiredResource = resolvedApis.find(api => api.resourceAppId === resolvedRequiredResource.resourceAppId);
+                if (requiredResource) {
+                    requiredResource.resourceAccess.push(...resolvedRequiredResource.resourceAccess);
+                }
+                else {
+                    resolvedApis.push(resolvedRequiredResource);
+                }
+            });
+        }
+        else {
+            const manifestApis = manifest.requiredResourceAccess;
+            manifestApis.forEach(manifestApi => {
+                resolvedApis.push(manifestApi);
+                const app = servicePrincipals.find(servicePrincipals => servicePrincipals.appId === manifestApi.resourceAppId);
+                if (app) {
+                    manifestApi.resourceAccess.forEach((res => {
+                        const resourceAccessPermission = {
+                            id: res.id,
+                            type: res.type
+                        };
+                        const oAuthValue = app.oauth2PermissionScopes.find(scp => scp.id === res.id)?.value;
+                        updateAppPermissions({
+                            spId: app.id,
+                            resourceAccessPermission,
+                            oAuth2PermissionValue: oAuthValue
+                        });
+                    }));
+                }
+            });
+        }
+        if (verbose) {
+            await logger.logToStderr(`Merged delegated and application permissions: ${JSON.stringify(resolvedApis, null, 2)}`);
+            await logger.logToStderr(`App role assignments: ${JSON.stringify(entraApp.appPermissions.flatMap(permission => permission.resourceAccess.filter(access => access.type === "Role")), null, 2)}`);
+            await logger.logToStderr(`OAuth2 permissions: ${JSON.stringify(entraApp.appPermissions.flatMap(permission => permission.scope), null, 2)}`);
+        }
+        return resolvedApis;
+    }
+};
+//# sourceMappingURL=entraApp.js.map

package/dist/utils/spo.js

@@ -500,10 +500,10 @@ export const spo = {
    * @param webUrl Web url
    * @param email The email of the user
    * @param logger the Logger object
-   * @param verbose set if verbose logging should be logged
+   * @param verbose set for verbose logging
    */
     async getUserByEmail(webUrl, email, logger, verbose) {
-        if (verbose) {
+        if (verbose && logger) {
             await logger.logToStderr(`Retrieving the spo user by email ${email}`);
         }
         const requestUrl = `${webUrl}/_api/web/siteusers/GetByEmail('${formatting.encodeQueryParameter(email)}')`;
@@ -574,10 +574,10 @@ export const spo = {
     * @param webUrl Web url
     * @param name The name of the group
     * @param logger the Logger object
-    * @param verbose set if verbose logging should be logged
+    * @param verbose set for verbose logging
     */
     async getGroupByName(webUrl, name, logger, verbose) {
-        if (verbose) {
+        if (verbose && logger) {
             await logger.logToStderr(`Retrieving the group by name ${name}`);
         }
         const requestUrl = `${webUrl}/_api/web/sitegroups/GetByName('${formatting.encodeQueryParameter(name)}')`;
@@ -596,10 +596,10 @@ export const spo = {
     * @param webUrl Web url
     * @param name the name of the role definition
     * @param logger the Logger object
-    * @param debug set if debug logging should be logged
+    * @param verbose set for verbose logging
     */
-    async getRoleDefinitionByName(webUrl, name, logger, debug) {
-        if (debug) {
+    async getRoleDefinitionByName(webUrl, name, logger, verbose) {
+        if (verbose && logger) {
             await logger.logToStderr(`Retrieving the role definitions for ${name}`);
         }
         const roledefinitions = await odata.getAllItems(`${webUrl}/_api/web/roledefinitions`);
@@ -1527,6 +1527,29 @@ export const spo = {
         const itemsResponse = await request.get(requestOptionsItems);
         return (itemsResponse);
     },
+    /**
+    * Retrieves the file by id.
+    * Returns a FileProperties object
+    * @param webUrl Web url
+    * @param id the id of the file
+    * @param logger the Logger object
+    * @param verbose set for verbose logging
+    */
+    async getFileById(webUrl, id, logger, verbose) {
+        if (verbose && logger) {
+            await logger.logToStderr(`Retrieving the file with id ${id}`);
+        }
+        const requestUrl = `${webUrl}/_api/web/GetFileById('${formatting.encodeQueryParameter(id)}')`;
+        const requestOptions = {
+            url: requestUrl,
+            headers: {
+                'accept': 'application/json;odata=nometadata'
+            },
+            responseType: 'json'
+        };
+        const file = await request.get(requestOptions);
+        return file;
+    },
     /**
      * Create a SharePoint copy job to copy a file/folder to another location.
      * @param webUrl Absolute web URL where the source file/folder is located.
@@ -1590,6 +1613,51 @@ export const spo = {
         // Get the destination object information
         const objectInfo = logs.find(l => l.Event === 'JobFinishedObjectInfo');
         return objectInfo;
+    },
+    /**
+     * Gets the site collection URL for a given web URL using SP Admin site.
+     * @param adminUrl The SharePoint admin URL
+     * @param siteId The site ID
+     * @param logger The logger object
+     * @param verbose If in verbose mode
+     * @returns Owner login name
+     */
+    async getPrimaryAdminLoginNameAsAdmin(adminUrl, siteId, logger, verbose) {
+        if (verbose) {
+            await logger.logToStderr('Getting the primary admin login name...');
+        }
+        const requestOptions = {
+            url: `${adminUrl}/_api/SPO.Tenant/sites('${siteId}')?$select=OwnerLoginName`,
+            headers: {
+                accept: 'application/json;odata=nometadata',
+                'content-type': 'application/json;charset=utf-8'
+            }
+        };
+        const response = await request.get(requestOptions);
+        const responseContent = JSON.parse(response);
+        return responseContent.OwnerLoginName;
+    },
+    /**
+     * Gets the primary owner login from a site.
+     * @param siteUrl The site URL
+     * @param logger The logger object
+     * @param verbose If in verbose mode
+     * @returns Owner login name
+     */
+    async getPrimaryOwnerLoginFromSite(siteUrl, logger, verbose) {
+        if (verbose) {
+            await logger.logToStderr('Getting the primary admin login name...');
+        }
+        const requestOptions = {
+            url: `${siteUrl}/_api/site/owner`,
+            method: 'GET',
+            headers: {
+                'accept': 'application/json;odata=nometadata'
+            },
+            responseType: 'json'
+        };
+        const responseContent = await request.get(requestOptions);
+        return responseContent?.LoginName;
     }
 };
 //# sourceMappingURL=spo.js.map

package/dist/utils/zod.js

@@ -60,7 +60,7 @@ function parseDefault(def, _options, currentOption) {
 function parseEnum(def, _options, currentOption) {
     if (currentOption) {
         currentOption.type = 'string';
-        currentOption.autocomplete = def.values;
+        currentOption.autocomplete = [...def.values];
     }
     return;
 }

package/docs/docs/_clisettings.mdx

@@ -2,6 +2,11 @@ Setting name|Definition|Default value
 ------------|----------|-------------
 `authType`|Default login method to use when running `m365 login` without the `--authType` option.|`deviceCode`
 `autoOpenLinksInBrowser`|Automatically open the browser for all commands which return a url and expect the user to copy paste this to the browser. For example when logging in, using `m365 login` in device code mode.|`false`
+`clientId`|ID of the default Entra ID app use by the CLI to authenticate|``
+`clientSecret`|Secret of the default Entra ID app use by the CLI to authenticate|``
+`clientCertificateFile`|Path to the file containing the client certificate to use for authentication|``
+`clientCertificateBase64Encoded`|Base64-encoded client certificate contents|``
+`clientCertificatePassword`|Password to the client certificate file|``
 `copyDeviceCodeToClipboard`|Automatically copy the device code to the clipboard when running `m365 login` command in device code mode|`false`
 `csvEscape`|Single character used for escaping; only apply to characters matching the quote and the escape options|`"`
 `csvHeader`|Display the column names on the first line|`true`
@@ -17,4 +22,4 @@ Setting name|Definition|Default value
 `prompt`|Prompts for missing values in required options and enables interactive selection when multiple values are available for a command that requires a specific value to be retrieved.|`true`
 `promptListPageSize`|By default, lists of choices longer than 7 will be paginated. Use this option to control how many choices will appear on the screen at once.|7
 `showHelpOnFailure`|Automatically display help when executing a command failed|`true`
-`showSpinner`|Display spinner when executing commands|`true`
+`tenantId`|ID of the default tenant to use when authenticating with|``

package/docs/docs/cmd/flow/recyclebinitem/recyclebinitem-list.mdx

@@ -0,0 +1,132 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# flow recyclebinitem list
+
+Lists all soft-deleted Power Automate flows within an environment
+
+## Usage
+
+```sh
+m365 flow recyclebinitem list [options]
+```
+
+## Options
+
+```md definition-list
+`-e, --environmentName <environmentName>`
+: The name of the environment.
+```
+
+<Global />
+
+## Remarks
+
+:::warning
+
+This command is based on an API that is currently in preview and is subject to change once the API reaches general availability.
+
+:::
+
+:::info
+
+To use this command, you must be a Global or Power Platform administrator.
+
+:::
+
+A Power Automate flow is soft-deleted when:
+- It's a non-solution flow.
+- It's been deleted less than 21 days ago.
+
+If the environment with the name you specified doesn't exist, you will get the `Access to the environment 'xyz' is denied.` error.
+
+## Examples
+
+List all soft-deleted flows within a specific environment
+
+```sh
+m365 flow recyclebinitem list --environmentName Default-d87a7535-dd31-4437-bfe1-95340acd55c5
+```
+
+## Response
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```json
+  [
+    {
+      "name": "26a9a283-af42-4c09-aa3e-60c3cc166b90",
+      "id": "/providers/Microsoft.ProcessSimple/environments/Default-d87a7535-dd31-4437-bfe1-95340acd55c5/flows/26a9a283-af42-4c09-aa3e-60c3cc166b90",
+      "type": "Microsoft.ProcessSimple/environments/flows",
+      "properties": {
+        "apiId": "/providers/Microsoft.PowerApps/apis/shared_logicflows",
+        "displayName": "Invoicing flow",
+        "state": "Deleted",
+        "createdTime": "2024-08-05T23:13:54Z",
+        "lastModifiedTime": "2024-08-05T23:14:00Z",
+        "flowSuspensionReason": "None",
+        "environment": {
+          "name": "Default-d87a7535-dd31-4437-bfe1-95340acd55c5",
+          "type": "Microsoft.ProcessSimple/environments",
+          "id": "/providers/Microsoft.ProcessSimple/environments/Default-d87a7535-dd31-4437-bfe1-95340acd55c5"
+        },
+        "definitionSummary": {
+          "triggers": [],
+          "actions": []
+        },
+        "creator": {
+          "tenantId": "a16e76a1-837f-4bf9-82dc-78874d18e434",
+          "objectId": "bd51c64d-c262-4184-ba3f-5361ea553820",
+          "userId": "bd51c64d-c262-4184-ba3f-5361ea553820",
+          "userType": "ActiveDirectory"
+        },
+        "flowFailureAlertSubscribed": false,
+        "isManaged": false,
+        "machineDescriptionData": {},
+        "flowOpenAiData": {
+          "isConsequential": false,
+          "isConsequentialFlagOverwritten": false
+        }
+      }
+    }
+  ]
+  ```
+
+  </TabItem>
+  <TabItem value="Text">
+
+  ```text
+  name                                  displayName
+  ------------------------------------  --------------
+  26a9a283-af42-4c09-aa3e-60c3cc166b90  Invoicing flow
+  ```
+
+  </TabItem>
+  <TabItem value="CSV">
+
+  ```csv
+  name,id,type
+  26a9a283-af42-4c09-aa3e-60c3cc166b90,/providers/Microsoft.ProcessSimple/environments/Default-d87a7535-dd31-4437-bfe1-95340acd55c5/flows/26a9a283-af42-4c09-aa3e-60c3cc166b90,Microsoft.ProcessSimple/environments/flows
+  ```
+
+  </TabItem>
+  <TabItem value="Markdown">
+
+  ```md
+  # flow recyclebinitem list --environmentName "Default-d87a7535-dd31-4437-bfe1-95340acd55c5"
+
+  Date: 06/08/2024
+
+  ## 26a9a283-af42-4c09-aa3e-60c3cc166b90 (/providers/Microsoft.ProcessSimple/environments/Default-d87a7535-dd31-4437-bfe1-95340acd55c5/flows/26a9a283-af42-4c09-aa3e-60c3cc166b90)
+
+  Property | Value
+  ---------|-------
+  name | 26a9a283-af42-4c09-aa3e-60c3cc166b90
+  id | /providers/Microsoft.ProcessSimple/environments/Default-d87a7535-dd31-4437-bfe1-95340acd55c5/flows/26a9a283-af42-4c09-aa3e-60c3cc166b90
+  type | Microsoft.ProcessSimple/environments/flows
+  ```
+
+  </TabItem>
+</Tabs>

package/docs/docs/cmd/flow/recyclebinitem/recyclebinitem-restore.mdx

@@ -0,0 +1,55 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# flow recyclebinitem restore
+
+Restores a soft-deleted Power Automate flow
+
+## Usage
+
+```sh
+m365 flow recyclebinitem restore [options]
+```
+
+## Options
+
+```md definition-list
+`-e, --environmentName <environmentName>`
+: The name of the environment where the flow is located.
+
+`-n, --flowName <flowName>`
+: The name of the Power Automate flow.
+```
+
+<Global />
+
+## Remarks
+
+:::warning
+
+This command is based on an API that is currently in preview and is subject to change once the API reaches general availability.
+
+:::
+
+:::info
+
+To use this command, you must be a Global or Power Platform administrator.
+
+:::
+
+When a Power Automate flow is restored, it will be automatically disabled. To make it operational again, you must [enable](../flow-enable.mdx) it.
+
+If the environment with the name you specified doesn't exist, you will get the `Access to the environment 'xyz' is denied.` error.
+
+## Examples
+
+Restores a soft-deleted flow within a specific environment
+
+```sh
+m365 flow recyclebinitem restore --environmentName Default-d87a7535-dd31-4437-bfe1-95340acd55c5 --flowName 5923cb07-ce1a-4a5c-ab81-257ce820109a
+```
+
+## Response
+
+The command won't return a response on success.