@microsoft/power-apps-native-host 0.2.22

package/lib/module/platform/PowerPlatformEnvironmentApi.js

@@ -0,0 +1,186 @@
+"use strict";
+
+/*!
+ * power-apps-native-host — PowerPlatformEnvironmentApi
+ *
+ * Mirrors the Host SDK's DefaultAppMetadataProvider.fetchAppMetadataFromPowerConfig
+ * pattern: resolves the Power Platform environment-scoped API endpoint from the
+ * environment GUID and region, then fetches linkedEnvironmentMetadata to obtain
+ * the Dataverse instanceUrl.
+ *
+ * Reference (Host SDK):
+ *   packages/power-apps-host/src/providers/defaults/DefaultAppMetadataProvider.ts
+ *   packages/power-apps-common/src/services/PowerPlatformApiDiscovery.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Region → API hostname suffix
+// Mirrors PowerPlatformApiDiscovery.getHostNameSuffix / getHexApiSuffixLength
+// ---------------------------------------------------------------------------
+
+const HOST_NAME_SUFFIX = {
+  local: 'api.powerplatform.localhost',
+  dev: 'api.dev.powerplatform.com',
+  test: 'api.test.powerplatform.com',
+  preprod: 'api.preprod.powerplatform.com',
+  preview: 'api.powerplatform.com',
+  // preview ring → prod endpoints
+  firstrelease: 'api.powerplatform.com',
+  prod: 'api.powerplatform.com',
+  gccmoderate: 'api.gov.powerplatform.microsoft.us',
+  gov: 'api.gov.powerplatform.microsoft.us',
+  gcchigh: 'api.high.powerplatform.microsoft.us',
+  high: 'api.high.powerplatform.microsoft.us',
+  dod: 'api.appsplatform.us',
+  mooncake: 'api.powerplatform.partner.microsoftonline.cn',
+  ex: 'api.powerplatform.eaglex.ic.gov',
+  rx: 'api.powerplatform.microsoft.scloud'
+};
+
+/** prod / firstrelease / preview use a 2-char hex suffix; all others use 1. */
+function hexSuffixLength(region) {
+  return region === 'prod' || region === 'firstrelease' || region === 'preview' ? 2 : 1;
+}
+
+/**
+ * Build the Power Platform environment-scoped API base URL.
+ *
+ * Algorithm (mirrors PowerPlatformApiDiscovery.generateDomain):
+ *   1. Strip dashes from the environment GUID to get a hex string.
+ *   2. Split into prefix (all but last N chars) and suffix (last N chars),
+ *      where N = 2 for prod/firstrelease, 1 for all other regions.
+ *   3. Compose: `{prefix}.{suffix}.environment.{hostNameSuffix}`
+ *
+ * Example (prod, environmentId = "d909aac0-59d0-e5b1-900d-c082ef5774d7"):
+ *   hexName  = "d909aac059d0e5b1900dc082ef5774d7"
+ *   suffix   = "d7"
+ *   prefix   = "d909aac059d0e5b1900dc082ef5774"
+ *   → "d909aac059d0e5b1900dc082ef5774.d7.environment.api.powerplatform.com"
+ */
+export function buildEnvironmentEndpoint(environmentId, region) {
+  const hostNameSuffix = HOST_NAME_SUFFIX[region] ?? HOST_NAME_SUFFIX['prod'];
+  const hexName = environmentId.toLowerCase().replace(/-/g, '');
+  const suffixLen = hexSuffixLength(region);
+  if (suffixLen >= hexName.length) {
+    throw new Error(`Cannot build Power Platform API endpoint: environment identifier too short after normalisation: "${hexName}"`);
+  }
+  const hexSuffix = hexName.substring(hexName.length - suffixLen);
+  const hexPrefix = hexName.substring(0, hexName.length - suffixLen);
+  return `https://${hexPrefix}.${hexSuffix}.environment.${hostNameSuffix}`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Token scope for the Power Platform management API (prod cluster).
+ * Non-prod clusters (test, gov, high, dev, mooncake, etc.) host the management
+ * API on their own audience, so prod-scope tokens are rejected with 401 by
+ * those clusters. Prefer {@link powerPlatformScope} when the region is known.
+ */
+export const POWER_PLATFORM_API_SCOPE = 'https://api.powerplatform.com/.default';
+
+/**
+ * Region-aware Power Platform management API scope. The audience must match the
+ * cluster the request is sent to; reuses the same region → hostname table as
+ * {@link buildEnvironmentEndpoint}.
+ */
+export function powerPlatformScope(region) {
+  const host = HOST_NAME_SUFFIX[region] ?? HOST_NAME_SUFFIX['prod'];
+  return `https://${host}/.default`;
+}
+import { getAppLogger, HostOperationNames } from "../telemetry/index.js";
+function getSafeErrorName(error) {
+  return error instanceof Error ? error.constructor.name : typeof error;
+}
+
+/**
+ * Fetch the Dataverse instanceUrl for a Power Platform environment by calling
+ * the environment-scoped Power Platform management API — the same call that
+ * the Host SDK's DefaultAppMetadataProvider makes to populate
+ * `databaseReferences[*].databaseDetails.linkedEnvironmentMetadata`.
+ *
+ * @param environmentId - Environment GUID (from power.config.json `environmentId`).
+ * @param region        - Cluster region string (from power.config.json `region`, default "prod").
+ * @param acquireToken  - Callback to obtain a bearer token for the given scopes.
+ *                        Scope will be {@link powerPlatformScope}`(region)`.
+ * @param bearerToken   - Optional pre-fetched bearer token for {@link powerPlatformScope}`(region)`.
+ *                        Pass this to avoid a redundant `acquireToken` round-trip when the
+ *                        caller has already obtained a token for the same audience.
+ * @returns The Dataverse org URL (e.g. "https://org12345.crm.dynamics.com"), or
+ *          `undefined` if the environment has no linked CDS database.
+ */
+export async function fetchInstanceUrl(environmentId, region, acquireToken, bearerToken) {
+  const scenario = getAppLogger().trackScenario(HostOperationNames.PlatformFetchInstanceUrl, {
+    environmentId,
+    region
+  });
+  try {
+    const baseUrl = buildEnvironmentEndpoint(environmentId, region);
+    const url = `${baseUrl}/powerapps/environment?api-version=1&%24filter=name+eq+%27${encodeURIComponent(environmentId)}%27`;
+    const token = bearerToken ?? (await acquireToken([powerPlatformScope(region)]));
+    if (!token) {
+      throw new Error('fetchInstanceUrl: failed to acquire Power Platform API token');
+    }
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`fetchInstanceUrl: environment API returned ${response.status} ${response.statusText}`);
+    }
+    const env = await response.json();
+    const instanceUrl = env.properties?.linkedEnvironmentMetadata?.instanceUrl;
+    scenario.complete({
+      hasInstanceUrl: instanceUrl !== undefined
+    });
+    return instanceUrl;
+  } catch (e) {
+    scenario.fail(undefined, {
+      errorName: getSafeErrorName(e)
+    });
+    throw e;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// buildCdsDataSources
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of a single Dataverse table entry inside power.config.json
+ * `databaseReferences[*].dataSources[*]`.
+ */
+
+/**
+ * Shape of a single database reference entry inside power.config.json
+ * `databaseReferences`.
+ */
+
+/**
+ * Build the CDS data source config array that the SDK reads via
+ * AppPowerAppsClientPlugin.getAppCdsDataSourceConfigsAsync.
+ *
+ * Pass the resolved Dataverse org URL (from useConnectionRefs) and the
+ * databaseReferences map from power.config.json.  The resulting array is
+ * passed directly to <PowerAppsHostProvider dataSources={...} />.
+ *
+ * @param databaseReferences - The `databaseReferences` map from power.config.json.
+ * @param dataverseOrgUrl    - The resolved Dataverse org URL
+ *                             (connectionRefs['commondataserviceforapps']?.datasetName).
+ *                             Pass an empty string before the org URL is known;
+ *                             the host provider will receive empty runtimeUrl entries
+ *                             and the SDK will not attempt Dataverse calls.
+ */
+export function buildCdsDataSources(databaseReferences, dataverseOrgUrl) {
+  return Object.values(databaseReferences).flatMap(dbRef => Object.values(dbRef.dataSources ?? {}).map(ds => ({
+    runtimeUrl: dataverseOrgUrl ? `${dataverseOrgUrl}/api/data/v9.0/` : '',
+    entitySetName: ds.entitySetName ?? '',
+    logicalName: ds.logicalName ?? '',
+    version: '9.2'
+  })));
+}

package/lib/module/platform/resolveConnections.js

@@ -0,0 +1,259 @@
+"use strict";
+
+/*!
+ * power-apps-native-host — resolveConnections
+ *
+ * Pure async helpers for the two connection-resolution strategies used by
+ * useConnectionRefs:
+ *
+ *  • resolveViaStaticRefs — per-connector resolution using the static
+ *    connectionReferences map from power.config.json.  Used by the Dev Player
+ *    and during local development (no appId) or when the launch API is
+ *    unavailable.  Handles pre-disambiguation ACL grants so inaccessible
+ *    connections are excluded before the user is asked to pick.
+ *
+ *  • applyAclGrants — post-resolution ACL grants used by the fast path
+ *    (production APKs via fetchAppLaunchData).
+ *
+ * Both helpers return / consume the shared AppLaunchResult shape so the
+ * hook orchestrator can handle them uniformly.
+ */
+
+import { addAadAppToConnectionAcl, parseJwtOid, SERVICE_POWERAPPS_SCOPE } from "./PowerPlatformConnectionApi.js";
+import { fetchInstanceUrl, buildEnvironmentEndpoint } from "./PowerPlatformEnvironmentApi.js";
+import { disambiguateConnections, extractConnectionId } from "../connections/disambiguate.js";
+import { ConnectionStatus } from "../connections/types.js";
+const API_VERSION = '1';
+
+// ---------------------------------------------------------------------------
+// ConnectorSchema
+// ---------------------------------------------------------------------------
+
+/**
+ * Connector schema entry generated by `generate-connector-schemas`.
+ * Keyed by data source name in the `schemaMap` passed to `useConnectionRefs`.
+ */
+
+// ---------------------------------------------------------------------------
+// resolveViaStaticRefs
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve connections from the static `connectionReferences` map.
+ *
+ * Steps:
+ *  1. Build an apiId → schema lookup.
+ *  2. In parallel: fetch the Dataverse instanceUrl and all connection instances
+ *     for every connector.
+ *  3. If `isvClientId` is set, run pre-disambiguation ACL grants — connections
+ *     where the grant fails are marked `NeedsAclGrant` and excluded from
+ *     resolution, prompting the user to create a new connection.
+ *  4. Disambiguate: resolve single matches, invoke callbacks for ambiguous /
+ *     missing cases, perform one-shot retries when `onMissingConnection` returns
+ *     `true`.
+ *  5. Build and return an `AppLaunchResult`-shaped object.
+ */
+export async function resolveViaStaticRefs({
+  connectionReferences,
+  schemaMap,
+  environmentId,
+  region,
+  acquireToken,
+  token,
+  isvClientId,
+  onDisambiguationNeeded,
+  onMissingConnection
+}) {
+  // Build apiId → schema lookup from the static refs.
+  const schemaByApiId = Object.fromEntries(Object.values(connectionReferences).map(ref => {
+    const schema = ref.dataSources.map(ds => schemaMap[ds]).find(Boolean);
+    return schema ? [ref.id, schema] : null;
+  }).filter(entry => entry !== null));
+  const base = buildEnvironmentEndpoint(environmentId, region);
+  const headers = {
+    Authorization: `Bearer ${token}`
+  };
+
+  // Fetch Dataverse instanceUrl and all connection instances in parallel.
+  const [instanceUrl, ...connResults] = await Promise.all([fetchInstanceUrl(environmentId, region, acquireToken, token), ...Object.entries(connectionReferences).map(async ([localRefId, ref]) => {
+    const schema = schemaByApiId[ref.id];
+    if (!schema) {
+      return {
+        localRefId,
+        apiId: ref.id,
+        dataSources: ref.dataSources,
+        instances: []
+      };
+    }
+    const url = `${base}/connectivity/apis/${schema.name}/connections` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+    try {
+      const res = await fetch(url, {
+        headers
+      });
+      if (!res.ok) {
+        return {
+          localRefId,
+          apiId: ref.id,
+          dataSources: ref.dataSources,
+          instances: []
+        };
+      }
+      const body = await res.json();
+      const instances = (body.value ?? []).map(c => ({
+        id: extractConnectionId(c.name),
+        name: c.name,
+        apiId: ref.id,
+        status: c.properties?.statuses?.[0]?.status === 'Connected' ? ConnectionStatus.Connected : ConnectionStatus.NotConnected,
+        displayName: c.properties?.displayName
+      }));
+      return {
+        localRefId,
+        apiId: ref.id,
+        dataSources: ref.dataSources,
+        instances
+      };
+    } catch {
+      return {
+        localRefId,
+        apiId: ref.id,
+        dataSources: ref.dataSources,
+        instances: []
+      };
+    }
+  })]);
+
+  // Pre-disambiguation ACL grants (ISV apps only).
+  //
+  // Connections where the grant fails are marked NeedsAclGrant so
+  // disambiguation treats them as unavailable and surfaces the
+  // "missing connection" flow, steering the user to create a new one.
+  if (isvClientId) {
+    const paToken = await acquireToken([SERVICE_POWERAPPS_SCOPE]);
+    const paOid = paToken ? parseJwtOid(paToken) : null;
+    if (paToken && paOid) {
+      await Promise.all(connResults.map(async r => {
+        const connId = schemaByApiId[r.apiId]?.name;
+        if (!connId) return;
+        await Promise.all(r.instances.map(async inst => {
+          if (inst.status !== ConnectionStatus.Connected) return;
+          const ok = await addAadAppToConnectionAcl(connId, inst.id, environmentId, isvClientId, paOid, paToken);
+          if (!ok) inst.status = ConnectionStatus.NeedsAclGrant;
+        }));
+      }));
+    }
+  }
+
+  // Disambiguation.
+  const allConnectionsByApiId = {};
+  for (const r of connResults) {
+    allConnectionsByApiId[r.apiId] = r.instances;
+  }
+  const disambiguationResults = disambiguateConnections(connectionReferences, allConnectionsByApiId);
+  const resolvedIds = {};
+  const unresolvedApiIds = [];
+  for (const dr of disambiguationResults) {
+    if (dr.result.kind === 'resolved') {
+      resolvedIds[dr.localRefId] = dr.result.connectionId;
+    } else if (dr.result.kind === 'ambiguous') {
+      const picked = onDisambiguationNeeded ? await onDisambiguationNeeded({
+        localRefId: dr.localRefId,
+        apiId: dr.apiId,
+        candidates: dr.result.candidates
+      }) : null;
+      // Fall back to the first Connected candidate so the app can still start.
+      resolvedIds[dr.localRefId] = picked ?? dr.result.candidates[0]?.id ?? '';
+    } else {
+      // kind === 'missing'
+      let retried = false;
+      if (onMissingConnection) {
+        retried = await onMissingConnection({
+          localRefId: dr.localRefId,
+          apiId: dr.apiId
+        });
+      }
+      if (retried) {
+        // One-shot retry for this specific connector.
+        const schema = schemaByApiId[dr.apiId];
+        if (schema) {
+          try {
+            const url = `${base}/connectivity/apis/${schema.name}/connections` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+            const res = await fetch(url, {
+              headers
+            });
+            if (res.ok) {
+              const body = await res.json();
+              const retryInstances = (body.value ?? []).map(c => ({
+                id: extractConnectionId(c.name),
+                name: c.name,
+                apiId: dr.apiId,
+                status: c.properties?.statuses?.[0]?.status === 'Connected' ? ConnectionStatus.Connected : ConnectionStatus.NotConnected
+              }));
+              const connected = retryInstances.find(i => i.status === ConnectionStatus.Connected);
+              if (connected) {
+                resolvedIds[dr.localRefId] = connected.id;
+                continue;
+              }
+            }
+          } catch {
+            // Fall through to missing.
+          }
+        }
+      }
+      resolvedIds[dr.localRefId] = '';
+      unresolvedApiIds.push(dr.apiId);
+    }
+  }
+  const dataverseOrgUrl = (instanceUrl ?? '').replace(/\/$/, '');
+
+  // Build the final AppConnectionReference map.
+  const connectionRefs = {};
+  for (const [localRefId, ref] of Object.entries(connectionReferences)) {
+    const schema = schemaByApiId[ref.id];
+    const connectionName = resolvedIds[localRefId] ?? '';
+    const isDataverse = ref.id.includes('commondataserviceforapps');
+    const entry = {
+      apiId: ref.id,
+      runtimeUrl: schema?.properties.primaryRuntimeUrl ?? '',
+      connectionName,
+      datasetName: isDataverse ? dataverseOrgUrl : ''
+    };
+    for (const ds of ref.dataSources) {
+      connectionRefs[ds] = entry;
+    }
+  }
+  return {
+    connectionRefs,
+    dataverseOrgUrl,
+    missingConnectors: unresolvedApiIds
+  };
+}
+
+// ---------------------------------------------------------------------------
+// applyAclGrants
+// ---------------------------------------------------------------------------
+
+/**
+ * Run idempotent post-resolution ACL grants on behalf of the ISV app.
+ *
+ * Used by the fast path (production APKs via `fetchAppLaunchData`) where the
+ * launch API has already resolved the user's connections — grants are applied
+ * after the fact so APIM accepts tokens issued to the ISV's AAD app.
+ *
+ * For the slow path the grants run before disambiguation inside
+ * `resolveViaStaticRefs`, where they can still influence which connections
+ * are considered available.
+ *
+ * Failures are swallowed — a failed grant will surface as a 403 at runtime
+ * when the connector is called.
+ */
+export async function applyAclGrants(connectionRefs, environmentId, isvClientId, acquireToken) {
+  const paToken = await acquireToken([SERVICE_POWERAPPS_SCOPE]);
+  const paOid = paToken ? parseJwtOid(paToken) : null;
+  if (!paToken || !paOid) return;
+  const seen = new Set();
+  await Promise.all(Object.values(connectionRefs).map(async ref => {
+    if (!ref.connectionName || seen.has(ref.connectionName)) return;
+    seen.add(ref.connectionName);
+    await addAadAppToConnectionAcl(ref.apiId, ref.connectionName, environmentId, isvClientId, paOid, paToken);
+  }));
+}