@knime/hub-features 1.22.4 → 1.24.0

package/src/authUtils/README.md

@@ -0,0 +1,123 @@
+# KNIME® Hub Auth Utils
+
+The auth utils can be used to implement authentication in the hub. The idea is to use them in conjunction with the [knime-hub-auth-rely] service. Please check the service docs for detailed infos about the authentication flow.
+
+[knime-hub-auth-rely]: https://github.com/knime/knime-hub-auth-rely
+
+## Common usage pattern
+
+First you need to setup the auth refresher. This will make sure that the auth identity information
+is fetched on critical authenticated paths. Normally, this means as part of a `vue-router` route guard
+or a `Nuxt` middleware.
+
+```ts
+/// router.ts
+import { authUtils } from "@knime/hub-features";
+
+const myMiddleware = (): NavigationGuard => {
+  // 1. First we create the refresher. This returns the function that
+  // schedules running the token refresher periodically
+  const authRefresher = authUtils.createAuthRefresher({
+    // `getIdentity` is just a fetch function that hits the API to get the
+    // account information; in a nutshell a user `id` and a `name`
+    getIdentity,
+  });
+
+  // 2. Here we're now returning the _actual_ navigation guard
+  return async () => {
+    try {
+      await authRefresher();
+      return true; // allow navigation
+    } catch (error) {
+      consola.error("Navigation middleware error", error);
+      return false; // cancel navigation
+    }
+  };
+};
+
+const router = createRouter({
+  history: createWebHistory(base),
+  routes: [
+    {
+      path: "/",
+      name: "Home",
+      component: HomeRouteComponent,
+      // 3. Simply setup your middleware for usage
+      beforeEnter: [myMiddleware()],
+
+      // 4. A simpler usage could have been
+      // beforeEnter: [authUtils.createAuthRefresher({ getIdentity })],
+    },
+  ],
+});
+```
+
+### Handle auth errors
+
+Another common pattern you'll need is to react to authentication errors (401/403) on your requests. There's different ways
+to do this depending on the setup, but it usually revolves around setting up some HTTP request interceptor that runs some
+code upon receveing a 401 (and optionally sometimes a 403).
+
+Below is an example of an `ofetch` interceptor and how you would use these utils for such a case
+
+```ts
+// interceptor.ts
+import { authUtils } from "@knime/hub-features";
+
+export const unauthorizedInterceptor: HttpInterceptor = {
+  response: {
+    onError: ({ response }) => {
+      if (response?.status === 401) {
+        // This function performs the redirection automatically.
+        authUtils.client.navigateToLogin({ wdywtg: window.location.href });
+
+        throw new Error("Auth failure");
+      }
+    },
+  },
+};
+```
+
+However, in the above example, the usage of `authUtils.client.navigateToLogin` is client-side code, which uses the `window` object to
+redirect. Therefore, this doesn't work on SSR. If you need a server-side redirect, or if you want more control of _how_ you redirect (e.g using Nuxt's `navigateTo` function)
+you can instead call another util which returns the login url and you can perform the redirection on your own:
+
+```ts
+// some-file.ts
+
+import { authUtils } from "@knime/hub-features";
+
+const someHandler = () => {
+  // ...
+  const loginPath = authUtils.paths.login({ wdywtg: to.fullPath });
+  return navigateTo(loginPath, {
+    external: true,
+    redirectCode: TEMPORARY_REDIRECT,
+  });
+
+  // ...
+};
+```
+
+### Accessing auth state
+
+With the middleware in place, you can now reference the auth state in your app by making use of the provided stateful composable:
+
+```ts
+/// some-file.ts
+import { authUtils } from "@knime/hub-features";
+
+const { loggedInUser, isLoggedIn } = authUtils.useAuthState();
+```
+
+This state is immutable and is owned and controlled by the auth refresher internally.
+
+### Stop refreshing the auth token
+
+In addition to the route middleware setup, you might run into cases where you want to stop the refresher manually. For this, simply import the corresponding function and call it:
+
+```ts
+import { authUtils } from "@knime/hub-features";
+
+authUtils.stopTokenRefresh();
+```

package/src/authUtils/client.ts

@@ -0,0 +1,18 @@
+import { logger } from "./logger";
+import { buildLoginPath, buildLogoutPath } from "./shared";
+
+/**
+ * Navigates to the login path. This function does not work on SSR
+ */
+export const navigateToLogin = ({ wdywtg }: { wdywtg?: string } = {}) => {
+  logger().debug("Navigating to login");
+  window.location.href = buildLoginPath({ wdywtg }); // NOSONAR - intended window usage
+};
+
+/**
+ * Navigates to the logout path. This function does not work on SSR
+ */
+export const navigateToLogout = ({ wdywtg }: { wdywtg?: string } = {}) => {
+  logger().debug("Navigating to logout");
+  window.location.href = buildLogoutPath({ wdywtg }); // NOSONAR - intended window usage
+};

package/src/authUtils/index.ts

@@ -0,0 +1,61 @@
+import * as client from "./client";
+import { logger } from "./logger";
+import { startRefresher, stopRefresher } from "./refresher";
+import { buildLoginPath, buildLogoutPath } from "./shared";
+import type { AuthRefresher } from "./types";
+import { setLoggedInUser, useAuthState } from "./useAuthState";
+
+/**
+ * This function does two main things:
+ * 1. Fetch the user identity and store it via the auth composable.
+ * 2. Start the background refresher which will renew tokens according to the
+ *    auth service TTL.
+ *
+ * Typical usage is from a route middleware for routes that require
+ * authentication. See README for a more in-depth example usage
+ *
+ * @param options AuthRefresher
+ * @returns a function that, when called, will load the identity (if needed)
+ * and start the token refresher. The returned function will throw if the
+ * underlying identity fetch fails.
+ */
+function createAuthRefresher(options: AuthRefresher) {
+  return async () => {
+    const { isLoggedIn } = useAuthState();
+
+    if (!isLoggedIn.value) {
+      try {
+        const identity = await options.getIdentity();
+
+        if (identity) {
+          logger().info("Fetched user identity", {
+            id: identity.id,
+            name: identity.name,
+          });
+
+          setLoggedInUser(identity);
+          startRefresher({ onRefreshComplete: options.onRefreshComplete });
+        } else {
+          logger().error("Logged in, but could not retrieve logged in user");
+        }
+      } catch (e) {
+        logger().error(
+          "Not logged in, http request interceptor should redirect to login",
+          e,
+        );
+        throw e;
+      }
+    }
+  };
+}
+
+export const authUtils = {
+  createAuthRefresher,
+  stopTokenRefresh: stopRefresher,
+  useAuthState,
+  /**
+   * These utilities don't work in SSR. You can leverage the `paths` helpers to redirect manually
+   */
+  client,
+  paths: { login: buildLoginPath, logout: buildLogoutPath },
+};

package/src/authUtils/logger.ts

@@ -0,0 +1 @@
+export const logger = () => consola.withTag("Auth Utils");

package/src/authUtils/refresher.ts

@@ -0,0 +1,65 @@
+import { navigateToLogout } from "./client";
+import { logger } from "./logger";
+import { AUTH_SERVICE_PATH } from "./shared";
+import type { AuthRefresher } from "./types";
+
+type Options = Pick<AuthRefresher, "onRefreshComplete">;
+
+const REFRESH_BUFFER = 10;
+/**
+ * Subtracts a random noise value from the ttl to refresh the token before it actually expires.
+ *
+ * @param {number}  ttlSeconds - time-to-live (TTL) in seconds
+ */
+const subtractRandomNoise = (ttlSeconds: number) => {
+  const randomBuffer = Math.random() * (REFRESH_BUFFER / 2); // NOSONAR using random numbers is safe here
+  return Math.floor((ttlSeconds - REFRESH_BUFFER - randomBuffer) * 1000);
+};
+
+let timeout: number | NodeJS.Timeout;
+
+/**
+ * Start proactively refreshing the token before it expires.
+ */
+export const startRefresher = (options: Options = {}) => {
+  logger().debug("Starting token refresher");
+
+  globalThis.clearTimeout(timeout);
+
+  const fetchData = async () => {
+    try {
+      const response = await fetch(`${AUTH_SERVICE_PATH}/refresh`);
+
+      if (!response.ok) {
+        throw new Error(`Error during auth refresh: ${response.status}`);
+      }
+
+      options?.onRefreshComplete?.();
+      const { expiry } = await response.json();
+
+      const msUntilRefresh = subtractRandomNoise(expiry);
+
+      logger().debug(
+        `Token is valid. Expires in ${expiry}s, refreshing in ${msUntilRefresh / 1000}s`,
+      );
+
+      timeout = globalThis.setTimeout(() => {
+        // eslint-disable-next-line no-void
+        void fetchData();
+      }, msUntilRefresh);
+    } catch (error) {
+      logger().warn(`Token refresh failed: ${error}, logging out`);
+      navigateToLogout({ wdywtg: "/?authError=refresh" });
+    }
+  };
+
+  // eslint-disable-next-line no-void
+  void fetchData();
+};
+
+export const stopRefresher = () => {
+  if (timeout !== undefined) {
+    logger().info("Stopping auth refresh timer");
+    globalThis.clearTimeout(timeout);
+  }
+};

package/src/authUtils/shared.ts

@@ -0,0 +1,25 @@
+/**
+ * Adds a "where do you want to go" `wdywtg` query param to the url. This
+ * will take the user to the URL contained within that param after the auth flow completes
+ */
+const addWdywtg = (url: string, wdywtg?: string) => {
+  if (wdywtg) {
+    const decodedWdywtg = decodeURIComponent(wdywtg);
+
+    // we decode an already-encoded wdywtg so that we can properly encode spaces
+    if (decodedWdywtg !== wdywtg) {
+      wdywtg = decodedWdywtg;
+    }
+
+    url += `?wdywtg=${encodeURIComponent(wdywtg)}`;
+  }
+  return url;
+};
+
+export const AUTH_SERVICE_PATH = "/_/auth";
+
+export const buildLoginPath = ({ wdywtg }: { wdywtg?: string } = {}) =>
+  addWdywtg(`${AUTH_SERVICE_PATH}/login`, wdywtg);
+
+export const buildLogoutPath = ({ wdywtg }: { wdywtg?: string } = {}) =>
+  addWdywtg(`${AUTH_SERVICE_PATH}/logout`, wdywtg);

package/src/authUtils/types.ts

@@ -0,0 +1,12 @@
+export type UserIdentity = { id: string; name: string };
+
+export type AuthRefresher = {
+  /**
+   * Fetcher function to obtain the basic user identity information
+   */
+  getIdentity: () => Promise<UserIdentity>;
+  /**
+   * Callback that runs after each completion of an auth token refresh
+   */
+  onRefreshComplete?: () => unknown;
+};

package/src/authUtils/useAuthState.ts

@@ -0,0 +1,19 @@
+import { computed, readonly, shallowRef } from "vue";
+
+import type { UserIdentity } from "./types";
+
+// Value is cached in the module scope
+const loggedInUser = shallowRef<UserIdentity | null>(null);
+
+export const setLoggedInUser = (user: UserIdentity) => {
+  loggedInUser.value = user;
+};
+
+export const useAuthState = () => {
+  const isLoggedIn = computed(() => Boolean(loggedInUser.value));
+
+  return {
+    loggedInUser: readonly(loggedInUser),
+    isLoggedIn,
+  };
+};

package/src/components/versions/composables/useVersionsApi.ts

@@ -70,18 +70,28 @@ export const useVersionsApi = ({
     }>;
   };
 
-  const fetchResourceLabels = ({
+  const fetchResourceLabels = async ({
     resourceType,
     resourceId,
   }: {
     resourceType: "savepoint";
     resourceId: string;
-  }) => {
-    return doHubRequest(
-      `/validation/validation/resources/${resourceType}/${resourceId}/labels`,
-    ).catch(() => ({ assignedLabels: [] })) as Promise<{
-      assignedLabels: Array<AssignedLabel>;
-    }>;
+  }): Promise<{
+    assignedLabels: Array<AssignedLabel>;
+  }> => {
+    try {
+      return await doHubRequest(
+        `/validation/validation/resources/${resourceType}/${resourceId}/labels`,
+      );
+    } catch (error) {
+      consola.error("useVersionsApi::Failed to fetch resource labels", {
+        resourceId,
+        resourceType,
+        error,
+      });
+
+      return { assignedLabels: [] };
+    }
   };
 
   const deleteVersion = ({
@@ -140,36 +150,50 @@ export const useVersionsApi = ({
   }: {
     accountName: string;
   }): Promise<HubAvatarData> => {
-    const accountInfo = await doHubRequest(`/accounts/name/${accountName}`, {
-      headers: {
-        Prefer: "representation=minimal",
-      },
-    });
+    try {
+      const accountInfo = await doHubRequest(`/accounts/name/${accountName}`, {
+        headers: {
+          Prefer: "representation=minimal",
+        },
+      });
 
-    return {
-      kind: accountInfo.type === "TEAM" ? "group" : "account",
-      name: accountInfo.name,
-      image: {
-        url: accountInfo.avatarUrl,
-        altText: `${accountInfo.realName ?? accountInfo.name} profile image`,
-      },
-    };
+      return {
+        kind: accountInfo.type === "TEAM" ? "group" : "account",
+        name: accountInfo.name,
+        image: {
+          url: accountInfo.avatarUrl,
+          altText: `${accountInfo.realName ?? accountInfo.name} profile image`,
+        },
+      };
+    } catch (error) {
+      consola.error("useVersionsApi::Failed to fetch user avatar", {
+        accountName,
+        error,
+      });
+
+      return {
+        kind: "account",
+        name: "?",
+        tooltip: "unknown",
+      };
+    }
   };
 
   const loadSavepointMetadata = async (
     savepoint: ItemSavepoint,
   ): Promise<WithAvatar & WithLabels> => {
-    return {
-      avatar: await getAvatar({
-        accountName: savepoint.version?.author ?? savepoint.author,
-      }),
-      labels: savepoint.itemVersionId
-        ? await fetchResourceLabels({
-            resourceType: "savepoint",
-            resourceId: savepoint.itemVersionId,
-          }).then((response) => response.assignedLabels)
-        : [],
-    };
+    const avatar = await getAvatar({
+      accountName: savepoint.version?.author ?? savepoint.author,
+    });
+
+    const labels = savepoint.itemVersionId
+      ? await fetchResourceLabels({
+          resourceType: "savepoint",
+          resourceId: savepoint.itemVersionId,
+        }).then((response) => response.assignedLabels)
+      : [];
+
+    return { avatar, labels };
   };
 
   const fetchItemSavepoints = ({

package/src/embeddingSDK/types.ts

@@ -35,9 +35,14 @@ export type EmbeddingContext = {
    */
   userIdleTimeout?: number;
   /**
-   * Whether the embedded application can send analytic and tracking events
+   * Configuration for analytics
    */
-  enableAnalytics?: boolean;
+  analytics?: {
+    /**
+     * Whether the embedded application can send analytic and tracking events
+     */
+    enabled: boolean;
+  };
 };
 
 type ShowNotificationEvent = {

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./useFileUpload";
 export * from "./useDownloadArtifact";
 export * from "./components/avatars";
 export * from "./embeddingSDK";
+export * from "./authUtils";