impeditmaiores 1.0.0

package/packages/arcgis-rest-auth/src/app-tokens.ts

@@ -0,0 +1,91 @@
+/* Copyright (c) 2018-2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions, request } from "@esri/arcgis-rest-request";
+
+/**
+ * Request app-specific token, passing in the token for the current app.
+ *
+ * This call returns a token after performing the same checks made by validateAppAccess.
+ * It returns an app-specific token of the signed-in user only if the user has access
+ * to the app and the encrypted platform cookie is valid.
+ *
+ * A scenario where an app would use this is if it is iframed into another platform app
+ * and recieves credentials via postMessage. Those credentials contain a token that is
+ * specific to the host app, so the embedded app would use `exchangeToken` to get one
+ * that is specific to itself.
+ *
+ * Note: This is only usable by Esri applications hosted on *arcgis.com, *esri.com or within
+ * an ArcGIS Enterprise installation. Custom applications can not use this.
+ *
+ * @param token
+ * @param clientId application
+ * @param portal
+ */
+export function exchangeToken(
+  token: string,
+  clientId: string,
+  portal: string = "https://www.arcgis.com/sharing/rest"
+): Promise<string> {
+  const url = `${portal}/oauth2/exchangeToken`;
+  const ro = {
+    method: "POST",
+    params: {
+      f: "json",
+      client_id: clientId,
+      token,
+    },
+  } as IRequestOptions;
+  // make the request and return the token
+  return request(url, ro).then((response) => response.token);
+}
+
+export interface IPlatformSelfResponse {
+  username: string;
+  token: string;
+}
+
+/**
+ * Request a token for a specific application using the esri_aopc encrypted cookie
+ *
+ * When a client app boots up, it will know it's clientId and the redirectUri for use
+ * in the normal /oauth/authorize pop-out oAuth flow.
+ *
+ * If the app sees an `esri_aopc` cookie (only set if the app is hosted on *.arcgis.com),
+ * it can call the /oauth2/platformSelf end-point passing in the clientId and redirectUri
+ * in headers, and it will recieve back an app-specific token, assuming the user has
+ * access to the app.
+ *
+ * Since there are scenarios where an app can boot using credintials/token from localstorage
+ * but those creds are not for the same user as the esri_aopc cookie, it is recommended that
+ * an app check the returned username against any existing identity they may have loaded.
+ *
+ * Note: This is only usable by Esri applications hosted on *arcgis.com, *esri.com or within
+ * an ArcGIS Enterprise installation. Custom applications can not use this.
+ * @param clientId
+ * @param redirectUri
+ * @param portal
+ */
+export function platformSelf(
+  clientId: string,
+  redirectUri: string,
+  portal: string = "https://www.arcgis.com/sharing/rest"
+): Promise<IPlatformSelfResponse> {
+  // TEMPORARY: the f=json should not be needed, but currently is
+  const url = `${portal}/oauth2/platformSelf?f=json`;
+  const ro = {
+    method: "POST",
+    headers: {
+      "X-Esri-Auth-Client-Id": clientId,
+      "X-Esri-Auth-Redirect-Uri": redirectUri,
+    },
+    // We need to ensure the cookies are sent as that's
+    // what the API uses to convert things
+    credentials: "include",
+    params: {
+      f: "json",
+    },
+  } as IRequestOptions;
+  // make the request and return the token
+  return request(url, ro);
+}

package/packages/arcgis-rest-auth/src/authenticated-request-options.ts

@@ -0,0 +1,24 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { ApplicationSession } from "./ApplicationSession";
+import { UserSession } from "./UserSession";
+
+import { IRequestOptions } from "@esri/arcgis-rest-request";
+
+/**
+ * Used internally by packages for requests that require user authentication.
+ */
+export interface IAuthenticatedRequestOptions extends IRequestOptions {
+  authentication: UserSession | ApplicationSession;
+}
+
+/**
+ * Used internally by packages for requests that require authentication.
+ */
+export interface IUserRequestOptions extends IRequestOptions {
+  /**
+   * A session representing a logged in user.
+   */
+  authentication: UserSession;
+}

package/packages/arcgis-rest-auth/src/federation-utils.ts

@@ -0,0 +1,85 @@
+import { cleanUrl } from "@esri/arcgis-rest-request";
+/**
+ * Used to test if a URL is an ArcGIS Online URL
+ */
+const arcgisOnlineUrlRegex = /^https?:\/\/(\S+)\.arcgis\.com.+/;
+
+/**
+ * Used to test if a URL is production ArcGIS Online Portal
+ */
+const arcgisOnlinePortalRegex = /^https?:\/\/(dev|devext|qa|qaext|www)\.arcgis\.com\/sharing\/rest+/;
+
+/**
+ * Used to test if a URL is an ArcGIS Online Organization Portal
+ */
+const arcgisOnlineOrgPortalRegex = /^https?:\/\/(?:[a-z0-9-]+\.maps(dev|devext|qa|qaext)?)?.\arcgis\.com\/sharing\/rest/;
+
+export function isOnline(url: string): boolean {
+  return arcgisOnlineUrlRegex.test(url);
+}
+
+export function normalizeOnlinePortalUrl(portalUrl: string): string {
+  if (!arcgisOnlineUrlRegex.test(portalUrl)) {
+    return portalUrl;
+  }
+
+  switch (getOnlineEnvironment(portalUrl)) {
+    case "dev":
+      return "https://devext.arcgis.com/sharing/rest";
+    case "qa":
+      return "https://qaext.arcgis.com/sharing/rest";
+    default:
+      return "https://www.arcgis.com/sharing/rest";
+  }
+}
+
+export function getOnlineEnvironment(url: string): string {
+  if (!arcgisOnlineUrlRegex.test(url)) {
+    return null;
+  }
+
+  const match = url.match(arcgisOnlineUrlRegex);
+  const subdomain = match[1].split(".").pop();
+
+  if (subdomain.includes("dev")) {
+    return "dev";
+  }
+
+  if (subdomain.includes("qa")) {
+    return "qa";
+  }
+
+  return "production";
+}
+
+export function isFederated(
+  owningSystemUrl: string,
+  portalUrl: string
+): boolean {
+  const normalizedPortalUrl = cleanUrl(
+    normalizeOnlinePortalUrl(portalUrl)
+  ).replace(/https?:\/\//, "");
+
+  const normalizedOwningSystemUrl = cleanUrl(owningSystemUrl).replace(
+    /https?:\/\//,
+    ""
+  );
+
+  return new RegExp(normalizedOwningSystemUrl, "i").test(normalizedPortalUrl);
+}
+
+export function canUseOnlineToken(
+  portalUrl: string,
+  requestUrl: string
+): boolean {
+  const portalIsOnline = isOnline(portalUrl);
+  const requestIsOnline = isOnline(requestUrl);
+  const portalEnv = getOnlineEnvironment(portalUrl);
+  const requestEnv = getOnlineEnvironment(requestUrl);
+
+  if (portalIsOnline && requestIsOnline && portalEnv === requestEnv) {
+    return true;
+  }
+
+  return false;
+}

package/packages/arcgis-rest-auth/src/fetch-token.ts

@@ -0,0 +1,50 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  IRequestOptions,
+  ITokenRequestOptions
+} from "@esri/arcgis-rest-request";
+
+interface IFetchTokenRawResponse {
+  access_token: string;
+  expires_in: number;
+  username: string;
+  ssl?: boolean;
+  refresh_token?: string;
+}
+
+export interface IFetchTokenResponse {
+  token: string;
+  expires: Date;
+  username: string;
+  ssl: boolean;
+  refreshToken?: string;
+}
+
+export function fetchToken(
+  url: string,
+  requestOptions: ITokenRequestOptions
+): Promise<IFetchTokenResponse> {
+  const options: IRequestOptions = requestOptions;
+  // we generate a response, so we can't return the raw response
+  options.rawResponse = false;
+
+  return request(url, options).then((response: IFetchTokenRawResponse) => {
+    const r: IFetchTokenResponse = {
+      token: response.access_token,
+      username: response.username,
+      expires: new Date(
+        // convert seconds in response to milliseconds and add the value to the current time to calculate a static expiration timestamp
+        Date.now() + (response.expires_in * 1000 - 1000)
+      ),
+      ssl: response.ssl === true
+    };
+    if (response.refresh_token) {
+      r.refreshToken = response.refresh_token;
+    }
+
+    return r;
+  });
+}

package/packages/arcgis-rest-auth/src/generate-token.ts

@@ -0,0 +1,35 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  IRequestOptions,
+  ITokenRequestOptions,
+  NODEJS_DEFAULT_REFERER_HEADER
+} from "@esri/arcgis-rest-request";
+
+export interface IGenerateTokenResponse {
+  token: string;
+  expires: number;
+  ssl: boolean;
+}
+
+export function generateToken(
+  url: string,
+  requestOptions: ITokenRequestOptions
+): Promise<IGenerateTokenResponse> {
+  const options: IRequestOptions = requestOptions;
+
+  /* istanbul ignore else */
+  if (
+    typeof window !== "undefined" &&
+    window.location &&
+    window.location.host
+  ) {
+    options.params.referer = window.location.host;
+  } else {
+    options.params.referer = NODEJS_DEFAULT_REFERER_HEADER;
+  }
+
+  return request(url, options);
+}

package/packages/arcgis-rest-auth/src/index.ts

@@ -0,0 +1,9 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+export * from "./ApplicationSession";
+export * from "./UserSession";
+export * from "./fetch-token";
+export * from "./generate-token";
+export * from "./authenticated-request-options";
+export { IUser } from "@esri/arcgis-rest-types";

package/packages/arcgis-rest-auth/src/validate-app-access.ts

@@ -0,0 +1,68 @@
+/* Copyright (c) 2018-2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions, request } from "@esri/arcgis-rest-request";
+
+export interface IAppAccess {
+  /**
+   * Verifies that the token is valid and the user has access to
+   * the specified app (clientId)
+   */
+  valid: boolean;
+  /**
+   * Should the app present the current user with a "View Only" mode
+   */
+  viewOnlyUserTypeApp: boolean;
+}
+
+/**
+ * Validates that the user has access to the application
+ * and if they user should be presented a "View Only" mode
+ *
+ * This is only needed/valid for Esri applications that are "licensed"
+ * and shipped in ArcGIS Online or ArcGIS Enterprise. Most custom applications
+ * should not need or use this.
+ *
+ * ```js
+ * import { validateAppAccess } from '@esri/arcgis-rest-auth';
+ *
+ * return validateAppAccess('your-token', 'theClientId')
+ * .then((result) => {
+ *    if (!result.valud) {
+ *      // redirect or show some other ui
+ *    } else {
+ *      if (result.viewOnlyUserTypeApp) {
+ *        // use this to inform your app to show a "View Only" mode
+ *      }
+ *    }
+ * })
+ * .catch((err) => {
+ *  // two possible errors
+ *  // invalid clientId: {"error":{"code":400,"messageCode":"GWM_0007","message":"Invalid request","details":[]}}
+ *  // invalid token: {"error":{"code":498,"message":"Invalid token.","details":[]}}
+ * })
+ * ```
+ *
+ * Note: This is only usable by Esri applications hosted on *arcgis.com, *esri.com or within
+ * an ArcGIS Enterprise installation. Custom applications can not use this.
+ *
+ * @param token platform token
+ * @param clientId application client id
+ * @param portal Optional
+ */
+export function validateAppAccess(
+  token: string,
+  clientId: string,
+  portal: string = "https://www.arcgis.com/sharing/rest"
+): Promise<IAppAccess> {
+  const url = `${portal}/oauth2/validateAppAccess`;
+  const ro = {
+    method: "POST",
+    params: {
+      f: "json",
+      client_id: clientId,
+      token,
+    },
+  } as IRequestOptions;
+  return request(url, ro);
+}

package/packages/arcgis-rest-auth/test/ApplicationSession.test.ts

@@ -0,0 +1,124 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { ApplicationSession } from "../src/index";
+import * as fetchMock from "fetch-mock";
+import { YESTERDAY, TOMORROW } from "./utils";
+
+describe("ApplicationSession", () => {
+  afterEach(fetchMock.restore);
+
+  describe(".getToken()", () => {
+    it("should return the cached token if it is not expired", done => {
+      const session = new ApplicationSession({
+        clientId: "id",
+        clientSecret: "secret",
+        token: "token",
+        expires: TOMORROW
+      });
+
+      Promise.all([
+        session.getToken("https://www.arcgis.com/sharing/rest/portals/self"),
+        session.getToken(
+          "https://services1.arcgis.com/MOCK_ORG/arcgis/rest/services/Private_Service/FeatureServer"
+        )
+      ])
+        .then(([token1, token2]) => {
+          expect(token1).toBe("token");
+          expect(token2).toBe("token");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+
+    it("should fetch a new token if the cached one is expired", done => {
+      const session = new ApplicationSession({
+        clientId: "id",
+        clientSecret: "secret",
+        token: "token",
+        expires: YESTERDAY
+      });
+
+      fetchMock.post("https://www.arcgis.com/sharing/rest/oauth2/token/", {
+        access_token: "new",
+        expires_in: 1800
+      });
+
+      Promise.all([
+        session.getToken("https://www.arcgis.com/sharing/rest/portals/self"),
+        session.getToken(
+          "https://services1.arcgis.com/MOCK_ORG/arcgis/rest/services/Private_Service/FeatureServer"
+        )
+      ])
+        .then(([token1, token2]) => {
+          expect(token1).toBe("new");
+          expect(token2).toBe("new");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+
+    it("should not make multiple refresh requests while a refresh is pending", done => {
+      const session = new ApplicationSession({
+        clientId: "id",
+        clientSecret: "secret",
+        token: "token",
+        expires: YESTERDAY
+      });
+
+      fetchMock.mock(
+        "https://www.arcgis.com/sharing/rest/oauth2/token/",
+        {
+          access_token: "new",
+          expires_in: 1800
+        },
+        { method: "POST", repeat: 1 }
+      );
+
+      Promise.all([
+        session.getToken("https://www.arcgis.com/sharing/rest/portals/self"),
+        session.getToken("https://www.arcgis.com/sharing/rest/portals/self")
+      ])
+        .then(([token1, token2]) => {
+          expect(token1).toBe("new");
+          expect(token2).toBe("new");
+          expect(
+            fetchMock.calls("https://www.arcgis.com/sharing/rest/oauth2/token/")
+              .length
+          ).toBe(1);
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+  });
+
+  it("should provide a method to refresh a session", done => {
+    const session = new ApplicationSession({
+      clientId: "id",
+      clientSecret: "secret",
+      token: "token",
+      expires: YESTERDAY
+    });
+
+    fetchMock.post("https://www.arcgis.com/sharing/rest/oauth2/token/", {
+      access_token: "new",
+      expires_in: 1800
+    });
+
+    session
+      .refreshSession()
+      .then(s => {
+        expect(s).toBe(session);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+});