@globus/sdk 0.7.2 → 1.0.0-alpha

package/src/lib/core/__tests__/global.spec.ts

@@ -0,0 +1,69 @@
+import { EnvironmentConfigurationError } from '../errors';
+import { getEnvironment, ENVIRONMENTS, getVerifySSL, getHttpTimeout } from '../global';
+
+describe('getEnvironment', () => {
+  const ORIGINAL_ENV_VARS = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV_VARS };
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV_VARS;
+  });
+
+  it('should be production when not set', () =>  {
+    delete process.env['GLOBUS_SDK_ENVIRONMENT'];
+    expect(getEnvironment()).toEqual(ENVIRONMENTS.PRODUCTION);
+  });
+
+  it('should be sandbox', () =>{
+    process.env['GLOBUS_SDK_ENVIRONMENT'] = ENVIRONMENTS.SANDBOX;
+    expect(getEnvironment()).toEqual(ENVIRONMENTS.SANDBOX);
+  });
+
+  it('should throw Error when environment string does not exist', () => {
+    process.env['GLOBUS_SDK_ENVIRONMENT'] = 'sindbox'; // <- intentional misspelling
+    expect(() => {
+      getEnvironment()
+    }).toThrow(EnvironmentConfigurationError);
+  });
+});
+
+describe('getVerifySSL', () => {
+  it('should always be true', () => {
+    expect(getVerifySSL()).toBe(true);
+  })
+});
+
+/**
+ * Basically just mirroring the `globus-python-sdk` testing
+ * for this env variable
+ * @see https://github.com/globus/globus-sdk-python/blob/e1d5a0df866b475d1aa1201520d337f09e2db608/tests/unit/test_base_client.py#L46
+ */
+describe('getHttpTimeout', () => {
+  const ORIGINAL_ENV_VARS = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV_VARS };
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV_VARS;
+  });
+
+  it('should be 60 seconds when not set', () => {
+    delete process.env['GLOBUS_SDK_HTTP_TIMEOUT'];
+    expect(getHttpTimeout()).toBe(60);
+  });
+
+  it('should be `null` when set to -1', () => {
+    process.env['GLOBUS_SDK_HTTP_TIMEOUT'] = '-1';
+    expect(getHttpTimeout()).toBeNull();
+  });
+
+  it('should be 120 seconds', () => {
+    process.env['GLOBUS_SDK_HTTP_TIMEOUT'] = '120';
+    expect(getHttpTimeout()).toBe(120);
+  });
+});

package/src/lib/core/__tests__/url.spec.ts

@@ -0,0 +1,105 @@
+import { EnvironmentConfigurationError } from "../errors";
+import { ENVIRONMENTS } from "../global";
+import { build, getServiceURL, stringifyParameters } from "../url";
+
+describe.each(Object.values(ENVIRONMENTS))(
+  "getServiceUrl succeeds",
+  (environment) => {
+    it("should produce a valid Globus Auth service URL", () => {
+      expect(() => {
+        getServiceURL("AUTH", environment);
+      }).not.toThrow();
+    });
+
+    it("should produce a valid Globus Transfer service URL", () => {
+      expect(() => {
+        getServiceURL("TRANSFER", environment);
+      }).not.toThrow();
+    });
+  }
+);
+
+describe("getServiceUrl failure", () => {
+  it("should throw an error when passed an invalid value", () => {
+    expect(() => {
+      getServiceURL("TRANSFER", "///%%%###");
+    }).toThrow();
+  });
+});
+
+describe.each(Object.values(ENVIRONMENTS))(
+  "build succeeds for all environments",
+  (environment) => {
+    const ORIGINAL_ENV_VARS = process.env;
+
+    beforeEach(() => {
+      process.env = {
+        ...ORIGINAL_ENV_VARS,
+        GLOBUS_SDK_ENVIRONMENT: environment,
+      };
+    });
+
+    afterAll(() => {
+      process.env = ORIGINAL_ENV_VARS;
+    });
+
+    it("should not throw errors for all environments", () => {
+      expect(() => {
+        build("AUTH", "test-path");
+      }).not.toThrow();
+    });
+  }
+);
+
+describe("build fails when invalid GLOBUS_SDK_ENVIRONMENT is set", () => {
+  const ORIGINAL_ENV_VARS = process.env;
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV_VARS;
+  });
+
+  it("should throw an error", () => {
+    process.env["GLOBUS_SDK_ENVIRONMENT"] = "sindbox"; // <- intentional misspelling
+
+    expect(() => {
+      build("AUTH", "test-path");
+    }).toThrow(EnvironmentConfigurationError);
+  });
+});
+
+describe("stringifyParameters", () => {
+  it("should serialize a simple object", () => {
+    expect(
+      stringifyParameters({ storage_gateway: "my-storage-gateway" })
+    ).toEqual("storage_gateway=my-storage-gateway");
+  });
+
+  it("should serialize an object with an array (single value)", () => {
+    /**
+     * Example from the GCS Manager API
+     * @see https://docs.globus.org/globus-connect-server/v5.4/api/openapi_Roles/#listRoles
+     */
+    expect(stringifyParameters({ include: ["all_roles"] })).toEqual(
+      "include=all_roles"
+    );
+  });
+
+  it("should serialize an object with an array (many values)", () => {
+    /**
+     * Example from the Groups V2 API
+     * @see https://groups.api.globus.org/redoc?_gl=1*16m8wdi*_ga*MTI3NTI4MzEzMi4xNjc1MTk1MTMw*_ga_7ZB89HGG0P*MTY5MDU3OTExNS4xNjUuMS4xNjkwNTc5MTk2LjAuMC4w#tag/groups/operation/get_statuses_v2_groups_statuses_get
+     */
+    expect(
+      stringifyParameters({
+        include: [
+          "memberships",
+          "my_memberships",
+          "policies",
+          "allowed_actions",
+        ],
+      })
+    ).toEqual(
+      "include=memberships%2Cmy_memberships%2Cpolicies%2Callowed_actions"
+    );
+  });
+});

package/src/lib/core/authorization.ts

@@ -0,0 +1,113 @@
+/**
+ * @description Session and authorization management via PKCE.
+ * @group Core
+ * @module
+ * @experimental
+ */
+import PKCE from "js-pkce";
+
+import type IConfig from "js-pkce/dist/IConfig";
+import type ITokenResponse from "js-pkce/dist/ITokenResponse";
+import { getAuthorizationEndpoint, getTokenEndpoint } from "../services/auth";
+import {
+  addTokenResponse,
+  getTokenForScope,
+  reset as resetTokens,
+} from "./consent";
+
+import { createStorage, StorageSystem } from "./storage";
+
+let storage: StorageSystem;
+
+type PKCEConfiguration = {
+  client_id?: IConfig["client_id"];
+  requested_scopes: IConfig["requested_scopes"];
+  redirect_uri: IConfig["redirect_uri"];
+};
+
+/**
+ * @experimental
+ */
+export class PKCEAuthorization {
+  #pkce: PKCE;
+  #configuration: IConfig;
+  #response: ITokenResponse | undefined;
+
+  constructor(configuration: PKCEConfiguration) {
+    storage = createStorage("localStorage");
+    if (!configuration.client_id) {
+      throw new Error("You must provide a `client_id`.");
+    }
+    this.#configuration = {
+      client_id: configuration.client_id,
+      authorization_endpoint: getAuthorizationEndpoint(),
+      token_endpoint: getTokenEndpoint(),
+      ...configuration,
+    };
+    this.#pkce = this.#createPKCEInstance();
+  }
+
+  #createPKCEInstance() {
+    return new PKCE(this.#configuration);
+  }
+
+  #resetPKCE() {
+    /**
+     * Resets js-pkce state
+     * @see https://github.com/bpedroza/js-pkce/blob/master/src/PKCE.ts
+     */
+    sessionStorage.removeItem("pkce_state");
+    sessionStorage.removeItem("pkce_code_verifier");
+  }
+
+  reset() {
+    this.#resetPKCE();
+    resetTokens();
+  }
+
+  redirect() {
+    this.reset();
+    window.location.replace(this.#pkce.authorizeUrl());
+  }
+
+  async handleCodeRedirect(options = { removeStateAndReplaceLocation: true }) {
+    const url = new URL(window.location.href);
+    const params = new URLSearchParams(url.search);
+
+    if (!params.get("code")) return;
+    const response = await this.#pkce.exchangeForAccessToken(url.toString());
+    this.#response = response;
+    addTokenResponse(this.#response);
+    // Remove PKCE-state from the URL since we have a token.
+    if (options.removeStateAndReplaceLocation) {
+      params.delete("code");
+      params.delete("state");
+      url.search = params.toString();
+      window.location.replace(url);
+    }
+  }
+
+  hasToken(): boolean {
+    return this.#configuration.requested_scopes
+      .split(" ")
+      .every((scope) => Boolean(getTokenForScope(scope)));
+  }
+
+  revoke() {
+    this.reset();
+  }
+}
+
+/**
+ * @experimental
+ */
+export function pkce(configuration: PKCEConfiguration) {
+  return new PKCEAuthorization(configuration);
+}
+
+/**
+ * @experimental
+ */
+export function incremental(configuration: PKCEConfiguration) {
+  return new PKCEAuthorization(configuration);
+}

package/src/lib/core/consent.ts

@@ -0,0 +1,34 @@
+import { getStorage } from "./storage";
+import type { Token, TokenResponse } from "../services/auth";
+
+import ITokenResponse from "js-pkce/dist/ITokenResponse";
+
+function isValidToken(check: unknown): check is Token {
+  const maybe = check as Token;
+  return Boolean(maybe.token_type && maybe.access_token);
+}
+
+function store(token: ITokenResponse) {
+  token.scope.split(" ").forEach((scope) => {
+    getStorage().set(scope, token);
+  });
+}
+
+export function addTokenResponse(token: ITokenResponse | TokenResponse) {
+  store(token);
+  if ("other_tokens" in token) {
+    token.other_tokens.forEach(store);
+  }
+}
+
+export function getTokenForScope(scope: string) {
+  const token = getStorage().get(scope);
+  if (!token || !isValidToken(token)) {
+    return null;
+  }
+  return `${token.token_type} ${token.access_token}`;
+}
+
+export function reset() {
+  getStorage().clear();
+}

package/src/lib/core/errors.ts

@@ -0,0 +1,8 @@
+export class EnvironmentConfigurationError extends Error {
+  override name = "EnvironmentConfigurationError";
+  constructor(variable: string, value: unknown) {
+    super();
+    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+    this.message = `Invalid configuration value provided for ${variable} (${value}).`;
+  }
+}

package/src/lib/core/fetch.ts

@@ -0,0 +1,38 @@
+import { fetch } from "./internals/fetch";
+import { getTokenForScope } from "./consent";
+
+type GlobusScope = string;
+
+export type FetchOverrides =
+  | (Omit<RequestInit, "headers"> & {
+      headers?: Record<string, string>;
+    })
+  | undefined;
+
+export function fetchWithScope(
+  scope: GlobusScope,
+  input: RequestInfo | URL,
+  fetchOverrides: FetchOverrides = {}
+) {
+  const headers = fetchOverrides.headers || {};
+  /**
+   * If an `Authorization` override header was provided, we skip any
+   * sort of lookup and use the provided value.
+   */
+  if (!headers?.["Authorization"]) {
+    const token = getTokenForScope(scope);
+    if (token) {
+      headers["Authorization"] = token;
+    }
+  }
+  /**
+   * If `Content-Type` header was not provided, and there is a body, we assume it is JSON.
+   */
+  if (!headers?.["Content-Type"] && fetchOverrides?.body) {
+    headers["Content-Type"] = "application/json";
+  }
+  return fetch(input, {
+    ...fetchOverrides,
+    headers,
+  });
+}

package/src/lib/core/global.ts

@@ -0,0 +1,128 @@
+import * as AUTH from "../services/auth/config";
+import * as TRANSFER from "../services/transfer/config";
+import * as FLOWS from "../services/flows/config";
+import * as GROUPS from "../services/groups/config";
+import * as SEARCH from "../services/search/config";
+
+import { EnvironmentConfigurationError } from "./errors";
+
+function getRuntime() {
+  return typeof window !== "undefined" ? window : process;
+}
+
+function isBrowser(runtime: Window | NodeJS.Process): runtime is Window {
+  return typeof window === typeof runtime;
+}
+
+function env<T extends string>(
+  key: string,
+  fallback: T | undefined = undefined
+): T | undefined {
+  const runtime = getRuntime();
+  let envConfiguration;
+  if (isBrowser(runtime)) {
+    envConfiguration = runtime;
+  } else {
+    envConfiguration = runtime.env;
+  }
+  if (key in envConfiguration) {
+    return (envConfiguration as Record<typeof key, T>)[key];
+  }
+  return fallback;
+}
+
+/**
+ * Handlers for: GLOBUS_SDK_ENVIRONMENT
+ */
+export const ENVIRONMENTS = {
+  PRODUCTION: "production",
+  PREVIEW: "preview",
+  STAGING: "staging",
+  SANDBOX: "sandbox",
+  INTEGRATION: "integration",
+  TEST: "test",
+} as const;
+
+export type Environment = (typeof ENVIRONMENTS)[keyof typeof ENVIRONMENTS];
+
+export function getEnvironment(): Environment {
+  const environment = env<Environment>(
+    "GLOBUS_SDK_ENVIRONMENT",
+    ENVIRONMENTS.PRODUCTION
+  );
+  if (!environment || !Object.values(ENVIRONMENTS).includes(environment)) {
+    throw new EnvironmentConfigurationError(
+      "GLOBUS_SDK_ENVIRONMENT",
+      environment
+    );
+  }
+  return environment;
+}
+
+export const SERVICES = {
+  [AUTH.ID]: AUTH.ID,
+  [TRANSFER.ID]: TRANSFER.ID,
+  [FLOWS.ID]: FLOWS.ID,
+  [GROUPS.ID]: GROUPS.ID,
+  [SEARCH.ID]: SEARCH.ID,
+};
+
+export type Service = keyof typeof SERVICES;
+
+export const SERVICE_HOSTS: Record<
+  Service,
+  Partial<Record<Environment, string>>
+> = {
+  [AUTH.ID]: AUTH.HOSTS,
+  [TRANSFER.ID]: TRANSFER.HOSTS,
+  [FLOWS.ID]: FLOWS.HOSTS,
+  [GROUPS.ID]: GROUPS.HOSTS,
+  [SEARCH.ID]: SEARCH.HOSTS,
+};
+
+/**
+ * Handlers for: GLOBUS_SDK_VERIFY_SSL
+ * Since disabling SSL is at least not-recommended, we consider
+ * this value to always be true, but provide a warning when it set
+ * to one of the falsey values for informational purposes.
+ *
+ * Taking direction from `globus-sdk-python` for possible false values
+ * @see https://github.com/globus/globus-sdk-python/blob/18eced9c12e2ec41745d1be183148845198b999c/src/globus_sdk/config/env_vars.py#L20
+ */
+export function getVerifySSL(): boolean {
+  const verifySSLTemp = (
+    env("GLOBUS_SDK_VERIFY_SSL", "true") as string
+  ).toLowerCase();
+  if (["n", "no", "f", "false", "off", "0"].includes(verifySSLTemp)) {
+    console.warn(
+      "Setting GLOBUS_SDK_VERIFY_SSL to false is disallowed in the Globus Javascript SDK. It will always true in this context"
+    );
+  }
+  return true;
+}
+
+/**
+ * Handlers for: GLOBUS_SDK_HTTP_TIMEOUT
+ */
+export function getHttpTimeout() {
+  const timeout = Number(env("GLOBUS_SDK_HTTP_TIMEOUT", "60"));
+  if (timeout === -1) {
+    return null;
+  }
+  return timeout;
+}
+
+function getServiceHost(service: Service, environment: Environment) {
+  return SERVICE_HOSTS[service][environment];
+}
+
+export function getServiceBaseUrl(
+  service: Service,
+  environment: Environment = getEnvironment()
+) {
+  const host = getServiceHost(service, environment);
+  return env(
+    `GLOBUS_SDK_SERVICE_URL_${service}`,
+    host ? `https://${host}` : undefined
+  );
+}

package/src/lib/core/internals/__mocks__/fetch.ts

@@ -0,0 +1,7 @@
+const actual: typeof import("../fetch") =
+  jest.requireActual("../fetch");
+
+module.exports = {
+  ...actual,
+  fetch: jest.fn().mockResolvedValue({}),
+};

package/{dist/browser/src/lib/core/internals/fetch.js → src/lib/core/internals/fetch.ts}

@@ -1,3 +1,2 @@
 import _fetch from "cross-fetch";
 export const fetch = _fetch;
-//# sourceMappingURL=fetch.js.map

package/src/lib/core/storage/index.ts

@@ -0,0 +1,57 @@
+import { MemoryStorage } from "./memory";
+import { LocalStorage } from "./local-storage";
+/**
+ * Acts as a basic wrapper for storage layers to make their surface APIs consistent.
+ */
+export interface StorageSystem {
+  get(key: string): unknown | undefined;
+  set(key: string, value: unknown): void;
+  remove(key: string): void;
+  clear(): void;
+}
+
+let storage: undefined | StorageSystem;
+type StorageOptions =
+  | "localStorage"
+  | "memory"
+  | {
+      new (): StorageSystem;
+    };
+
+/**
+ * Returns the active storage system or creates an instance for the running process.
+ */
+export function createStorage(
+  storageType: StorageOptions = "memory"
+): StorageSystem {
+  if (!storage) {
+    let Factory;
+    if (storageType === "localStorage") {
+      Factory = LocalStorage;
+    } else if (storageType === "memory") {
+      Factory = MemoryStorage;
+    } else {
+      Factory = storageType;
+    }
+    storage = new Factory();
+  }
+  return storage;
+}
+
+export default createStorage;
+
+export function getStorage() {
+  if (!storage) {
+    throw Error("You must create a storage system.");
+  }
+  return storage;
+}
+
+/**
+ * A private method for resetting the storage system. This is primarily used to reset
+ * the storage system during testing.
+ * @private
+ */
+export function __reset() {
+  storage = undefined;
+}

package/src/lib/core/storage/local-storage.ts

@@ -0,0 +1,20 @@
+import { StorageSystem } from "./index";
+
+export class LocalStorage implements StorageSystem {
+  get<T>(key: string): T | null | unknown {
+    const value = localStorage.getItem(key);
+    return value !== null ? JSON.parse(value) : null;
+  }
+
+  set(key: string, value: unknown) {
+    localStorage.setItem(key, JSON.stringify(value));
+  }
+
+  remove(key: string) {
+    localStorage.removeItem(key);
+  }
+
+  clear() {
+    localStorage.clear();
+  }
+}

package/src/lib/core/storage/memory.ts

@@ -0,0 +1,21 @@
+import type { StorageSystem } from "./index";
+
+export class MemoryStorage implements StorageSystem {
+  #cache: Record<string, unknown> = {};
+
+  get(key: string) {
+    return this.#cache[key];
+  }
+
+  set(key: string, value: unknown) {
+    this.#cache[key] = value;
+  }
+
+  remove(key: string) {
+    delete this.#cache[key];
+  }
+
+  clear() {
+    this.#cache = {};
+  }
+}

package/src/lib/core/storage/storage.spec.ts

@@ -0,0 +1,30 @@
+import type { StorageSystem } from "./index";
+
+import storage, { __reset } from "./index";
+import { MemoryStorage } from "./memory";
+import { LocalStorage } from "./local-storage";
+
+describe("storage", () => {
+  afterEach(() => {
+    __reset();
+  });
+
+  it("default storage interface (memory)", () => {
+    expect(storage()).toBeInstanceOf(MemoryStorage);
+  });
+
+  it("can be configured using known interface", () => {
+    expect(storage("localStorage")).toBeInstanceOf(LocalStorage);
+  });
+
+  it("can be provided a custom storage interface", () => {
+    expect(storage(CustomStorage)).toBeInstanceOf(CustomStorage);
+  });
+});
+
+class CustomStorage implements StorageSystem {
+  get(key: string) {}
+  set(key: string, value: any): void {}
+  remove(key: string): void {}
+  clear(): void {}
+}