@microsoft/power-apps-native-host 0.2.25 → 0.3.3

package/lib/module/platform/PowerPlatformConnectionApi.js

@@ -1,595 +0,0 @@
-"use strict";
-
-/*!
- * power-apps-native-host — PowerPlatformConnectionApi
- *
- * Typed wrappers around the Power Platform environment-scoped connectivity API
- * for connection CRUD operations and connector metadata retrieval.
- *
- * These mirror the endpoints used by ConnectorsApi in @microsoft/power-apps-common
- * but are implemented as plain async functions so they have no external dependencies.
- */
-
-import { buildEnvironmentEndpoint, powerPlatformScope } from "./PowerPlatformEnvironmentApi.js";
-import { ConnectionStatus } from "../connections/types.js";
-import { extractConnectionId } from "../connections/disambiguate.js";
-import { getAppLogger, HostOperationNames } from "../telemetry/index.js";
-import { debugLog, debugWarn } from "../logger.js";
-
-// Power Platform connectivity API version used across all calls here.
-const API_VERSION = '1';
-
-// Power Apps RP — used for connection sharing (modifyPermissions).
-const POWER_APPS_RP_BASE = 'https://api.powerapps.com';
-function getSafeErrorName(error) {
-  return error instanceof Error ? error.constructor.name : typeof error;
-}
-
-/**
- * Token scope for the Power Apps RP (api.powerapps.com).
- * Required when calling modifyPermissions to register a service principal
- * in the connection ACE so that APIM accepts third-party app tokens at runtime.
- */
-export const SERVICE_POWERAPPS_SCOPE = 'https://service.powerapps.com/.default';
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Generate a random connection ID as a 32-char lowercase hex string (UUID v4
- * without dashes), matching the format Power Platform uses for connection
- * resource names (e.g. "326561a0849744d5ae75c9bcaca1e5f1").
- */
-function generateConnectionId() {
-  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
-    return crypto.randomUUID().replace(/-/g, '');
-  }
-  // Fallback: manual UUID v4 bit pattern, returned as 32 hex chars.
-  return 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'.replace(/[xy]/g, c => {
-    const r = Math.random() * 16 | 0;
-    return (c === 'x' ? r : r & 0x3 | 0x8).toString(16);
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Connector metadata
-// ---------------------------------------------------------------------------
-
-/** Subset of connector metadata returned by the Power Platform API. */
-
-/**
- * Fetch metadata for a single connector from the Power Platform API.
- *
- * @param connectorId  - Connector short name (e.g. "shared_office365users")
- *                       or full API path suffix.
- * @param environmentId - Environment GUID.
- * @param region        - Cluster region string (default "prod").
- * @param token         - Pre-acquired Power Platform API bearer token.
- */
-export async function fetchConnectorMetadata(connectorId, environmentId, region, token) {
-  const base = buildEnvironmentEndpoint(environmentId, region);
-  const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}` + `?$filter=environment eq '${environmentId}'&api-version=${API_VERSION}`;
-  try {
-    const res = await fetch(url, {
-      headers: {
-        Authorization: `Bearer ${token}`
-      }
-    });
-    if (!res.ok) return null;
-    const body = await res.json();
-    return {
-      name: body.name ?? connectorId,
-      displayName: body.properties?.displayName ?? connectorId,
-      iconUri: body.properties?.iconUri ?? '',
-      description: body.properties?.description ?? '',
-      isFirstParty: body.properties?.isFirstParty ?? false
-    };
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Connection listing
-// ---------------------------------------------------------------------------
-
-/**
- * Fetch all connections for a given connector in the environment.
- * Returns only the `NativeConnectionInstance` shape used by the disambiguation layer.
- */
-export async function fetchConnectionsForConnector(connectorId, environmentId, region, token) {
-  const base = buildEnvironmentEndpoint(environmentId, region);
-  const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}/connections` + `?$filter=environment eq '${environmentId}'&api-version=${API_VERSION}`;
-  try {
-    const res = await fetch(url, {
-      headers: {
-        Authorization: `Bearer ${token}`
-      }
-    });
-    if (!res.ok) return [];
-    const body = await res.json();
-    return (body.value ?? []).map(c => ({
-      id: extractConnectionId(c.name),
-      name: c.name,
-      apiId: `/providers/Microsoft.PowerApps/apis/${connectorId}`,
-      status: c.properties?.statuses?.[0]?.status === 'Connected' ? ConnectionStatus.Connected : ConnectionStatus.NotConnected,
-      displayName: c.properties?.displayName
-    }));
-  } catch {
-    return [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Connection creation (implicit OAuth)
-// ---------------------------------------------------------------------------
-
-/**
- * Result of initiating an OAuth connection creation.
- *
- * `pending` — the connection has been created but is not yet authenticated.
- *   The `consentLink` URL must be opened (in a WebView or browser) so the
- *   user can complete the OAuth consent flow. Poll `pollConnectionStatus`
- *   until the status changes to "Connected".
- *
- * `connected` — the connection was created and is already Connected (e.g.,
- *   first-party SSO connections that do not need explicit OAuth consent).
- *
- * `error` — creation failed; `message` contains the error description.
- */
-
-/**
- * Create a new connection for a connector in the user's environment.
- *
- * Calls:
- *   POST {envBase}/connectivity/apis/{connectorId}/connections
- *
- * If the response contains a `consentLink`, the connection needs OAuth
- * completion (caller should open the URL and then poll `pollConnectionStatus`).
- * If the connection status is already "Connected", returns `connected`.
- *
- * @param connectorId     - Connector short name (e.g. "shared_office365users").
- * @param environmentId   - Environment GUID.
- * @param region          - Cluster region.
- * @param token           - Power Platform API bearer token.
- * @param displayName     - Optional display name for the new connection.
- * @param oauthRedirectUrl - Redirect URL sent to getConsentLink. The OAuth provider
- *                           will redirect the user here after consent. Defaults to
- *                           the standard native-client redirect accepted by Power Platform.
- */
-export async function createConnection(connectorId, environmentId, region, token, displayName, oauthRedirectUrl = 'https://login.microsoftonline.com/oauth2/nativeclient') {
-  const scenario = getAppLogger().trackScenario(HostOperationNames.PlatformCreateConnection, {
-    connectorId
-  });
-  try {
-    const base = buildEnvironmentEndpoint(environmentId, region);
-    const connectionId = generateConnectionId();
-    const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}/connections/${connectionId}` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
-    const body = {
-      properties: {
-        environment: {
-          name: environmentId
-        },
-        connectionParameters: {},
-        consentInfo: {
-          redirectUrl: oauthRedirectUrl
-        },
-        ...(displayName ? {
-          displayName
-        } : {})
-      }
-    };
-    const res = await fetch(url, {
-      method: 'PUT',
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'Content-Type': 'application/json'
-      },
-      body: JSON.stringify(body)
-    });
-    if (!res.ok) {
-      const errText = await res.text().catch(() => res.statusText);
-      const result = {
-        status: 'error',
-        message: `HTTP ${res.status}: ${errText}`
-      };
-      scenario.completeWithError({
-        httpStatus: res.status
-      });
-      return result;
-    }
-    const data = await res.json();
-    const connectionName = data.name ?? connectionId;
-    const connectionStatus = data.properties?.statuses?.[0]?.status ?? '';
-    if (connectionStatus === 'Connected') {
-      scenario.complete({
-        result: 'connected'
-      });
-      return {
-        status: 'connected',
-        connectionName
-      };
-    }
-
-    // Fetch the OAuth consent link from the dedicated endpoint.
-    // Use the pre-generated connectionId directly — not the full resource name —
-    // so the path segment is never double-encoded.
-    const consentUrl = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}` + `/connections/${connectionId}/getConsentLink` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
-    const consentRes = await fetch(consentUrl, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'Content-Type': 'application/json'
-      },
-      body: JSON.stringify({
-        redirectUrl: oauthRedirectUrl
-      })
-    });
-    if (consentRes.ok) {
-      const consentData = await consentRes.json();
-      const browserFallbackUrl = consentData.consentLink ?? '';
-
-      // For first-party connectors (O365, SharePoint, Dataverse…) attempt silent
-      // SSO by POSTing the current bearer token to firstPartyLoginUri.
-      // If the server accepts it the connection becomes Connected without a browser.
-      if (consentData.firstPartyLoginUri) {
-        try {
-          const ssoRes = await fetch(consentData.firstPartyLoginUri, {
-            method: 'POST',
-            headers: {
-              Authorization: `Bearer ${token}`,
-              'Content-Type': 'application/json'
-            },
-            body: JSON.stringify({
-              accessToken: token
-            })
-          });
-          if (ssoRes.ok) {
-            // Silent SSO succeeded — no browser needed.
-            scenario.complete({
-              result: 'connected_sso'
-            });
-            return {
-              status: 'connected',
-              connectionName
-            };
-          }
-        } catch {
-          // Silent SSO network error — fall through to browser consent.
-        }
-      }
-
-      // Fall back to browser-based consent flow.
-      if (browserFallbackUrl) {
-        scenario.complete({
-          result: 'pending_oauth'
-        });
-        return {
-          status: 'pending',
-          connectionName,
-          consentLink: browserFallbackUrl
-        };
-      }
-    }
-
-    // No consent link — treat as already connected (e.g. SSO connectors).
-    scenario.complete({
-      result: 'connected_no_consent'
-    });
-    return {
-      status: 'connected',
-      connectionName
-    };
-  } catch (e) {
-    scenario.fail(undefined, {
-      errorName: getSafeErrorName(e)
-    });
-    return {
-      status: 'error',
-      message: String(e)
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Connection status polling
-// ---------------------------------------------------------------------------
-
-/**
- * Poll a connection's status until it is "Connected" or a timeout is reached.
- *
- * @param connectionName - The connection resource name (from createConnection result).
- * @param environmentId  - Environment GUID.
- * @param region         - Cluster region.
- * @param token          - Power Platform API bearer token.
- * @param options.intervalMs  - Polling interval in ms (default 2000).
- * @param options.timeoutMs   - Maximum time to wait in ms (default 60000).
- * @returns The resolved `NativeConnectionInstance` if Connected, or `null` if timed out.
- */
-export async function pollConnectionStatus(connectorId, connectionName, environmentId, region, acquireToken, options = {}) {
-  const {
-    intervalMs = 2000,
-    timeoutMs = 60_000
-  } = options;
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const token = await acquireToken([powerPlatformScope(region)]);
-    if (!token) return null;
-    const base = buildEnvironmentEndpoint(environmentId, region);
-    const connectionId = extractConnectionId(connectionName);
-    const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}/connections/${connectionId}` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
-    try {
-      const res = await fetch(url, {
-        headers: {
-          Authorization: `Bearer ${token}`
-        }
-      });
-      if (res.ok) {
-        const data = await res.json();
-        const status = data.properties?.statuses?.[0]?.status ?? '';
-        if (status === 'Connected') {
-          return {
-            id: extractConnectionId(data.name ?? connectionName),
-            name: data.name ?? connectionName,
-            apiId: data.properties?.apiId ?? '',
-            status: ConnectionStatus.Connected,
-            displayName: data.properties?.displayName
-          };
-        }
-      }
-    } catch {
-      // Transient network error — continue polling.
-    }
-    await new Promise(resolve => {
-      const timer = setTimeout(resolve, intervalMs);
-      // Allow GC to clean up the timer reference.
-      if (typeof timer === 'object' && timer !== null && 'unref' in timer) {
-        timer.unref();
-      }
-    });
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Consent code confirmation
-// ---------------------------------------------------------------------------
-
-/**
- * Confirm a consent code returned by the APIM consent server in the OAuth
- * redirect URL (`?code=<commitTokenCode>`).
- *
- * The consent server embeds a 32-char hex CommitTokenCode in the redirect URL
- * when the OAuth exchange completes successfully. POSTing it here causes APIM
- * to exchange it for the real OAuth tokens and activate the connection
- * (status → Connected).
- *
- * When the redirect URL uses a custom scheme (e.g. `expo-app://oauth-callback`),
- * the consent server may instead return `?error=no+code+returned` and activate
- * the connection server-side. In that case this function is not called and the
- * caller should poll `pollConnectionStatus` directly.
- *
- * @param connectorId   - Connector short name (e.g. "shared_office365users").
- * @param connectionId  - Bare connection hex ID (no connector prefix).
- * @param environmentId - Environment GUID.
- * @param region        - Cluster region.
- * @param token         - Power Platform API bearer token.
- * @param code          - CommitTokenCode from the redirect URL `?code=` param.
- * @returns `true` if the server accepted the code, `false` otherwise.
- */
-export async function confirmConsentCode(connectorId, connectionId, environmentId, region, token, code) {
-  const base = buildEnvironmentEndpoint(environmentId, region);
-  const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}` + `/connections/${connectionId}/confirmConsentCode` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
-  try {
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'Content-Type': 'application/json'
-      },
-      body: JSON.stringify({
-        code
-      })
-    });
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// PowerApps environment — fetch published app launch data
-// ---------------------------------------------------------------------------
-
-/**
- * Processed result of the PowerApps app launch API call, ready to be applied
- * directly to the NativePowerAppsBridge without further network calls.
- */
-
-/**
- * Fetch app launch data from the Power Platform environment-scoped launch
- * endpoint and process it into the shape the NativePowerAppsBridge needs.
- *
- * A single call returns everything required to run the app:
- *  - `app.properties.connectionReferences` — connectors the app requires
- *  - `apis[]`                              — connector metadata (primaryRuntimeUrl)
- *  - `connections[]`                       — the current user's resolved connections
- *  - `app.properties.environment.properties.linkedEnvironmentMetadata.instanceUrl`
- *                                          — Dataverse org URL
- *
- * Endpoint (environment-scoped, same base as all Power Platform API calls):
- *   GET {envEndpoint}/powerapps/apps/{appId}/launch
- *       ?api-version=2&lastKnownGoodPublishedVersion=true
- *
- * Authentication: bearer token for {@link powerPlatformScope}`(region)`.
- *
- * @param appId         - PowerApps app GUID (from `power.config.json` → `appId`).
- * @param environmentId - Environment GUID.
- * @param region        - Cluster region (default "prod").
- * @param token         - Bearer token for {@link powerPlatformScope}`(region)`.
- * @returns Processed launch data, or `null` if the call fails.
- */
-export async function fetchAppLaunchData(appId, environmentId, region, token) {
-  const base = buildEnvironmentEndpoint(environmentId, region);
-  const url = `${base}/powerapps/apps/${encodeURIComponent(appId)}/launch` + `?api-version=2&lastKnownGoodPublishedVersion=true`;
-  try {
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'Content-Type': 'application/json'
-      },
-      body: '{}'
-    });
-    if (!res.ok) return null;
-    const data = await res.json();
-    const connRefRaw = data.app?.properties?.connectionReferences ?? {};
-    const apisRaw = data.apis ?? [];
-    const connectionsRaw = data.connections ?? [];
-
-    // Dataverse org URL from the embedded environment metadata.
-    const instanceUrl = data.app?.properties?.environment?.properties?.linkedEnvironmentMetadata?.instanceUrl;
-    const dataverseOrgUrl = (instanceUrl ?? '').replace(/\/$/, '');
-
-    // connectorShortName → primaryRuntimeUrl  (from apis[])
-    const runtimeUrlByConnector = {};
-    for (const api of apisRaw) {
-      if (api.name && api.properties?.primaryRuntimeUrl) {
-        // Normalise the key to lowercase to match the id normalisation below.
-        runtimeUrlByConnector[api.name.toLowerCase()] = api.properties.primaryRuntimeUrl;
-      }
-    }
-
-    // connectorShortName → first Connected connection name  (from connections[])
-    const connectionNameByConnector = {};
-    for (const conn of connectionsRaw) {
-      const rawApiId = conn.properties?.apiId ?? '';
-      const connectorName = (rawApiId.includes('/') ? rawApiId.split('/').pop() ?? rawApiId : rawApiId).toLowerCase();
-      if (!connectorName || !conn.name) continue;
-      const isConnected = conn.properties?.statuses?.[0]?.status === 'Connected';
-      // Keep only the first Connected instance per connector.
-      if (isConnected && !connectionNameByConnector[connectorName]) {
-        connectionNameByConnector[connectorName] = conn.name;
-      }
-    }
-    const connectionRefs = {};
-    const missingConnectors = [];
-    for (const ref of Object.values(connRefRaw)) {
-      const rawId = ref.id ?? '';
-      // Normalise: strip full RP path → short connector name, lowercase.
-      // e.g. "/providers/microsoft.powerapps/apis/shared_office365users"
-      //   → "shared_office365users"
-      const connectorName = (rawId.includes('/') ? rawId.split('/').pop() ?? rawId : rawId).toLowerCase();
-      if (!connectorName) continue;
-      const runtimeUrl = runtimeUrlByConnector[connectorName] ?? '';
-      const connectionName = connectionNameByConnector[connectorName] ?? '';
-      const isDataverse = connectorName.includes('commondataserviceforapps');
-      const dataSources = ref.dataSources ?? [];
-      if (!connectionName) {
-        missingConnectors.push(connectorName);
-      }
-      const entry = {
-        apiId: connectorName,
-        runtimeUrl,
-        connectionName,
-        datasetName: isDataverse ? dataverseOrgUrl : ''
-      };
-      for (const ds of dataSources) {
-        connectionRefs[ds] = entry;
-      }
-    }
-    return {
-      connectionRefs,
-      dataverseOrgUrl,
-      missingConnectors
-    };
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Connection ACL — add ISV app to connection ACL
-// ---------------------------------------------------------------------------
-
-/**
- * Decode the `oid` (object ID) claim from a JWT access token.
- *
- * The oid claim is in the base64url-encoded payload section (middle part).
- * Available in Hermes (React Native) via the global `atob`.
- */
-export function parseJwtOid(jwtToken) {
-  try {
-    const parts = jwtToken.split('.');
-    if (parts.length !== 3) return null;
-    const payload = parts[1];
-    // base64url → base64: replace - with + and _ with /, add padding
-    const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
-    const padded = base64 + '==='.slice((base64.length + 3) % 4);
-    const decoded = atob(padded);
-    const json = JSON.parse(decoded);
-    return typeof json['oid'] === 'string' ? json['oid'] : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Add the ISV's AAD application (client) ID to the connection's ACL AppIds
- * list via the Power Apps RP `addAadAppToConnectionAcl` endpoint.
- *
- * The RP finds the user's existing ACE (identified by `userOid`) and appends
- * `isvClientId` to its `AppIds` list. APIM's stage-2 token check verifies
- * that the requesting token's `appid` is present in this list, so without
- * this call APIM returns 403 "missing connection ACL" for third-party tokens.
- *
- * POST https://api.powerapps.com/providers/Microsoft.PowerApps/environments/{environmentId}
- *      /apis/{connectorId}/connections/{connectionId}/addAadAppToConnectionAcl
- *      ?api-version=2016-11-01
- *
- * Body: { "aadApplicationId": "<ISV client ID>", "objectId": "<user OID>" }
- *
- * @param connectorId   - Connector short name (e.g. "shared_office365users").
- * @param connectionId  - Bare 32-char hex connection ID.
- * @param environmentId - Environment GUID.
- * @param isvClientId   - The ISV's AAD application (client) ID.
- * @param userOid       - The signed-in user's AAD object ID (oid JWT claim).
- * @param token         - Bearer token for `https://service.powerapps.com/.default`.
- */
-export async function addAadAppToConnectionAcl(connectorId, connectionId, environmentId, isvClientId, userOid, token) {
-  const url = `${POWER_APPS_RP_BASE}/providers/Microsoft.PowerApps/environments/${encodeURIComponent(environmentId)}` + `/apis/${encodeURIComponent(connectorId)}` + `/connections/${encodeURIComponent(connectionId)}/addAadAppToConnectionAcl` + `?api-version=2016-11-01`;
-  const reqBody = {
-    aadApplicationId: isvClientId,
-    objectId: userOid
-  };
-  debugLog('[addAadAppToConnectionAcl] POST', url, JSON.stringify(reqBody));
-  try {
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'Content-Type': 'application/json'
-      },
-      body: JSON.stringify(reqBody)
-    });
-    const resText = await res.text().catch(() => '');
-    debugLog(`[addAadAppToConnectionAcl] HTTP ${res.status}`, resText);
-    if (!res.ok) {
-      debugWarn(`[addAadAppToConnectionAcl] failed HTTP ${res.status} for connection ${connectionId}: ${resText}`);
-      getAppLogger().trackErrorEvent(HostOperationNames.PlatformConnectionAclGrant, {
-        phase: 'addAadAppToConnectionAcl',
-        reason: 'httpError',
-        httpStatus: res.status
-      });
-    }
-    return res.ok;
-  } catch (e) {
-    debugWarn('[addAadAppToConnectionAcl] error:', e);
-    getAppLogger().trackErrorEvent(HostOperationNames.PlatformConnectionAclGrant, {
-      phase: 'addAadAppToConnectionAcl',
-      reason: 'exception'
-    });
-    return false;
-  }
-}