@backstage/core-app-api 0.5.0-next.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @backstage/core-app-api
 
+## 0.5.2
+
+### Patch Changes
+
+- 40775bd263: Switched out the `GithubAuth` implementation to use the common `OAuth2` implementation. This relies on the simultaneous change in `@backstage/plugin-auth-backend` that enabled access token storage in cookies rather than the current solution that's based on `LocalStorage`.
+
+  > **NOTE:** Make sure you upgrade the `auth-backend` deployment before or at the same time as you deploy this change.
+
+## 0.5.2-next.0
+
+### Patch Changes
+
+- 40775bd263: Switched out the `GithubAuth` implementation to use the common `OAuth2` implementation. This relies on the simultaneous change in `@backstage/plugin-auth-backend` that enabled access token storage in cookies rather than the current solution that's based on `LocalStorage`.
+
+  > **NOTE:** Make sure you upgrade the `auth-backend` deployment before or at the same time as you deploy this change.
+
+## 0.5.1
+
+### Patch Changes
+
+- f959c22787: Asynchronous methods on the identity API can now reliably be called at any time, including early in the bootstrap process or prior to successful sign-in.
+
+  Previously in such situations, a `Tried to access IdentityApi before app was loaded` error would be thrown. Now, those methods will wait and resolve eventually (as soon as a concrete identity API is provided).
+
+## 0.5.0
+
+### Minor Changes
+
+- ceebe25391: Removed deprecated `SignInResult` type, which was replaced with the new `onSignInSuccess` callback.
+
+### Patch Changes
+
+- fb565073ec: Add an `allowUrl` callback option to `FetchMiddlewares.injectIdentityAuth`
+- f050eec2c0: Added validation during the application startup that detects if there are any plugins present that have not had their required external routes bound. Failing the validation will cause a hard crash as it is a programmer error. It lets you detect early on that there are dangling routes, rather than having them cause an error later on.
+- Updated dependencies
+  - @backstage/core-plugin-api@0.6.0
+  - @backstage/config@0.1.13
+
 ## 0.5.0-next.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode, PropsWithChildren, ComponentType } from 'react';
 import PropTypes from 'prop-types';
-import { ApiHolder, ApiRef, ApiFactory, AnyApiRef, ProfileInfo, BackstageIdentityResponse, OAuthRequestApi, DiscoveryApi, AuthProviderInfo, OAuthApi, SessionApi, SessionState, AuthRequestOptions, gitlabAuthApiRef, googleAuthApiRef, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, oktaAuthApiRef, auth0AuthApiRef, microsoftAuthApiRef, oneloginAuthApiRef, bitbucketAuthApiRef, atlassianAuthApiRef, AlertApi, AlertMessage, AnalyticsApi, AnalyticsEvent, AppThemeApi, AppTheme, ErrorApi, ErrorApiError, ErrorApiErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, FetchApi, IdentityApi, OAuthRequesterOptions, OAuthRequester, PendingOAuthRequest, StorageApi, StorageValueSnapshot, BackstagePlugin, IconComponent, ExternalRouteRef, AnyApiFactory, RouteRef, SubRouteRef } from '@backstage/core-plugin-api';
+import { ApiHolder, ApiRef, ApiFactory, AnyApiRef, ProfileInfo, BackstageIdentityResponse, OAuthRequestApi, DiscoveryApi, AuthProviderInfo, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, OAuthApi, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, SessionApi, SessionState, AuthRequestOptions, oktaAuthApiRef, auth0AuthApiRef, microsoftAuthApiRef, oneloginAuthApiRef, bitbucketAuthApiRef, atlassianAuthApiRef, AlertApi, AlertMessage, AnalyticsApi, AnalyticsEvent, AppThemeApi, AppTheme, ErrorApi, ErrorApiError, ErrorApiErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, FetchApi, IdentityApi, OAuthRequesterOptions, OAuthRequester, PendingOAuthRequest, StorageApi, StorageValueSnapshot, BackstagePlugin, IconComponent, ExternalRouteRef, AnyApiFactory, RouteRef, SubRouteRef } from '@backstage/core-plugin-api';
 import * as _backstage_types from '@backstage/types';
 import { Observable, JsonValue } from '@backstage/types';
 import { Config, AppConfig } from '@backstage/config';
@@ -130,16 +130,11 @@ declare type AuthApiCreateOptions = {
  *
  * @public
  */
-declare class GithubAuth implements OAuthApi, SessionApi {
-    private readonly sessionManager;
-    static create(options: OAuthApiCreateOptions): GithubAuth;
-    private constructor();
-    signIn(): Promise<void>;
-    signOut(): Promise<void>;
-    sessionState$(): Observable<SessionState>;
-    getAccessToken(scope?: string, options?: AuthRequestOptions): Promise<string>;
-    getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentityResponse | undefined>;
-    getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>;
+declare class GithubAuth {
+    static create(options: OAuthApiCreateOptions): typeof githubAuthApiRef.T;
+    /**
+     * @deprecated This method is deprecated and will be removed in a future release.
+     */
     static normalizeScope(scope?: string): Set<string>;
 }
 
@@ -510,14 +505,16 @@ declare class FetchMiddlewares {
      *
      * The header injection only happens on allowlisted URLs. Per default, if the
      * `config` option is passed in, the `backend.baseUrl` is allowlisted, unless
-     * the `urlPrefixAllowlist` option is passed in, in which case it takes
-     * precedence. If you pass in neither config nor an allowlist, the middleware
-     * will have no effect.
+     * the `urlPrefixAllowlist` or `allowUrl` options are passed in, in which case
+     * they take precedence. If you pass in neither config nor an
+     * allowlist/callback, the middleware will have no effect since effectively no
+     * request will match the (nonexistent) rules.
      */
     static injectIdentityAuth(options: {
         identityApi: IdentityApi;
         config?: Config;
         urlPrefixAllowlist?: string[];
+        allowUrl?: (url: string) => boolean;
         header?: {
             name: string;
             value: (backstageToken: string) => string;

package/dist/index.esm.js

@@ -725,167 +725,7 @@ class AuthSessionStore {
   }
 }
 
-class OptionalRefreshSessionManagerMux {
-  constructor(options) {
-    this.stateTracker = new SessionStateTracker();
-    this.sessionCanRefresh = options.sessionCanRefresh;
-    this.staticSessionManager = options.staticSessionManager;
-    this.refreshingSessionManager = options.refreshingSessionManager;
-  }
-  async getSession(options) {
-    const staticSession = await this.staticSessionManager.getSession({
-      ...options,
-      optional: true
-    });
-    if (staticSession) {
-      this.stateTracker.setIsSignedIn(true);
-      return staticSession;
-    }
-    const session = await this.refreshingSessionManager.getSession(options);
-    if (!session) {
-      this.stateTracker.setIsSignedIn(false);
-      return void 0;
-    }
-    if (this.sessionCanRefresh(session)) {
-      this.stateTracker.setIsSignedIn(true);
-      return session;
-    }
-    this.staticSessionManager.setSession(session);
-    this.stateTracker.setIsSignedIn(true);
-    return session;
-  }
-  async removeSession() {
-    await Promise.all([
-      this.refreshingSessionManager.removeSession(),
-      this.staticSessionManager.removeSession()
-    ]);
-    this.stateTracker.setIsSignedIn(false);
-  }
-  sessionState$() {
-    return this.stateTracker.sessionState$();
-  }
-}
-
-const githubSessionSchema = z.object({
-  providerInfo: z.object({
-    accessToken: z.string(),
-    scopes: z.set(z.string()),
-    expiresAt: z.date().optional()
-  }),
-  profile: z.object({
-    email: z.string().optional(),
-    displayName: z.string().optional(),
-    picture: z.string().optional()
-  }),
-  backstageIdentity: z.object({
-    id: z.string(),
-    token: z.string(),
-    identity: z.object({
-      type: z.literal("user"),
-      userEntityRef: z.string(),
-      ownershipEntityRefs: z.array(z.string())
-    })
-  })
-});
-
 const DEFAULT_PROVIDER$a = {
-  id: "github",
-  title: "GitHub",
-  icon: () => null
-};
-class GithubAuth {
-  constructor(sessionManager) {
-    this.sessionManager = sessionManager;
-  }
-  static create(options) {
-    const {
-      discoveryApi,
-      environment = "development",
-      provider = DEFAULT_PROVIDER$a,
-      oauthRequestApi,
-      defaultScopes = ["read:user"]
-    } = options;
-    const connector = new DefaultAuthConnector({
-      discoveryApi,
-      environment,
-      provider,
-      oauthRequestApi,
-      sessionTransform(res) {
-        return {
-          ...res,
-          providerInfo: {
-            accessToken: res.providerInfo.accessToken,
-            scopes: GithubAuth.normalizeScope(res.providerInfo.scope),
-            expiresAt: res.providerInfo.expiresInSeconds ? new Date(Date.now() + res.providerInfo.expiresInSeconds * 1e3) : void 0
-          }
-        };
-      }
-    });
-    const refreshingSessionManager = new RefreshingAuthSessionManager({
-      connector,
-      defaultScopes: new Set(defaultScopes),
-      sessionScopes: (session) => session.providerInfo.scopes,
-      sessionShouldRefresh: (session) => {
-        const { expiresAt } = session.providerInfo;
-        if (!expiresAt) {
-          return false;
-        }
-        const expiresInSec = (expiresAt.getTime() - Date.now()) / 1e3;
-        return expiresInSec < 60 * 5;
-      }
-    });
-    const staticSessionManager = new AuthSessionStore({
-      manager: new StaticAuthSessionManager({
-        connector,
-        defaultScopes: new Set(defaultScopes),
-        sessionScopes: (session) => session.providerInfo.scopes
-      }),
-      storageKey: `${provider.id}Session`,
-      schema: githubSessionSchema,
-      sessionScopes: (session) => session.providerInfo.scopes
-    });
-    const sessionManagerMux = new OptionalRefreshSessionManagerMux({
-      refreshingSessionManager,
-      staticSessionManager,
-      sessionCanRefresh: (session) => session.providerInfo.expiresAt !== void 0
-    });
-    return new GithubAuth(sessionManagerMux);
-  }
-  async signIn() {
-    await this.getAccessToken();
-  }
-  async signOut() {
-    await this.sessionManager.removeSession();
-  }
-  sessionState$() {
-    return this.sessionManager.sessionState$();
-  }
-  async getAccessToken(scope, options) {
-    var _a;
-    const session = await this.sessionManager.getSession({
-      ...options,
-      scopes: GithubAuth.normalizeScope(scope)
-    });
-    return (_a = session == null ? void 0 : session.providerInfo.accessToken) != null ? _a : "";
-  }
-  async getBackstageIdentity(options = {}) {
-    const session = await this.sessionManager.getSession(options);
-    return session == null ? void 0 : session.backstageIdentity;
-  }
-  async getProfile(options = {}) {
-    const session = await this.sessionManager.getSession(options);
-    return session == null ? void 0 : session.profile;
-  }
-  static normalizeScope(scope) {
-    if (!scope) {
-      return /* @__PURE__ */ new Set();
-    }
-    const scopeList = Array.isArray(scope) ? scope : scope.split(/[\s|,]/).filter(Boolean);
-    return new Set(scopeList);
-  }
-}
-
-const DEFAULT_PROVIDER$9 = {
   id: "oauth2",
   title: "Your Identity Provider",
   icon: () => null
@@ -895,7 +735,7 @@ class OAuth2 {
     const {
       discoveryApi,
       environment = "development",
-      provider = DEFAULT_PROVIDER$9,
+      provider = DEFAULT_PROVIDER$a,
       oauthRequestApi,
       defaultScopes = [],
       scopeTransform = (x) => x
@@ -972,6 +812,37 @@ class OAuth2 {
   }
 }
 
+const DEFAULT_PROVIDER$9 = {
+  id: "github",
+  title: "GitHub",
+  icon: () => null
+};
+class GithubAuth {
+  static create(options) {
+    const {
+      discoveryApi,
+      environment = "development",
+      provider = DEFAULT_PROVIDER$9,
+      oauthRequestApi,
+      defaultScopes = ["read:user"]
+    } = options;
+    return OAuth2.create({
+      discoveryApi,
+      oauthRequestApi,
+      provider,
+      environment,
+      defaultScopes
+    });
+  }
+  static normalizeScope(scope) {
+    if (!scope) {
+      return /* @__PURE__ */ new Set();
+    }
+    const scopeList = Array.isArray(scope) ? scope : scope.split(/[\s|,]/).filter(Boolean);
+    return new Set(scopeList);
+  }
+}
+
 const DEFAULT_PROVIDER$8 = {
   id: "gitlab",
   title: "GitLab",
@@ -1497,29 +1368,24 @@ function createFetchApi(options) {
 }
 
 class IdentityAuthInjectorFetchMiddleware {
-  constructor(identityApi, urlPrefixAllowlist, headerName, headerValue) {
+  constructor(identityApi, allowUrl, headerName, headerValue) {
     this.identityApi = identityApi;
-    this.urlPrefixAllowlist = urlPrefixAllowlist;
+    this.allowUrl = allowUrl;
     this.headerName = headerName;
     this.headerValue = headerValue;
   }
   static create(options) {
     var _a, _b;
-    const allowlist = [];
-    if (options.urlPrefixAllowlist) {
-      allowlist.push(...options.urlPrefixAllowlist);
-    } else if (options.config) {
-      allowlist.push(options.config.getString("backend.baseUrl"));
-    }
+    const matcher = buildMatcher(options);
     const headerName = ((_a = options.header) == null ? void 0 : _a.name) || "authorization";
     const headerValue = ((_b = options.header) == null ? void 0 : _b.value) || ((token) => `Bearer ${token}`);
-    return new IdentityAuthInjectorFetchMiddleware(options.identityApi, allowlist.map((prefix) => prefix.replace(/\/$/, "")), headerName, headerValue);
+    return new IdentityAuthInjectorFetchMiddleware(options.identityApi, matcher, headerName, headerValue);
   }
   apply(next) {
     return async (input, init) => {
       const request = new Request(input, init);
       const { token } = await this.identityApi.getCredentials();
-      if (request.headers.get(this.headerName) || !this.urlPrefixAllowlist.some((prefix) => request.url === prefix || request.url.startsWith(`${prefix}/`)) || typeof token !== "string" || !token) {
+      if (request.headers.get(this.headerName) || typeof token !== "string" || !token || !this.allowUrl(request.url)) {
         return next(input, init);
       }
       request.headers.set(this.headerName, this.headerValue(token));
@@ -1527,6 +1393,20 @@ class IdentityAuthInjectorFetchMiddleware {
     };
   }
 }
+function buildMatcher(options) {
+  if (options.allowUrl) {
+    return options.allowUrl;
+  } else if (options.urlPrefixAllowlist) {
+    return buildPrefixMatcher(options.urlPrefixAllowlist);
+  } else if (options.config) {
+    return buildPrefixMatcher([options.config.getString("backend.baseUrl")]);
+  }
+  return () => false;
+}
+function buildPrefixMatcher(prefixes) {
+  const trimmedPrefixes = prefixes.map((prefix) => prefix.replace(/\/$/, ""));
+  return (url) => trimmedPrefixes.some((prefix) => url === prefix || url.startsWith(`${prefix}/`));
+}
 
 function join(left, right) {
   if (!right || right === "/") {
@@ -2138,7 +2018,7 @@ const RouteTracker = ({ tree }) => {
   }));
 };
 
-function validateRoutes(routePaths, routeParents) {
+function validateRouteParameters(routePaths, routeParents) {
   const notLeafRoutes = new Set(routeParents.values());
   notLeafRoutes.delete(void 0);
   for (const route of routeParents.keys()) {
@@ -2167,6 +2047,21 @@ function validateRoutes(routePaths, routeParents) {
     }
   }
 }
+function validateRouteBindings(routeBindings, plugins) {
+  for (const plugin of plugins) {
+    if (!plugin.externalRoutes) {
+      continue;
+    }
+    for (const [name, externalRouteRef] of Object.entries(plugin.externalRoutes)) {
+      if (externalRouteRef.optional) {
+        continue;
+      }
+      if (!routeBindings.has(externalRouteRef)) {
+        throw new Error(`External route '${name}' of the '${plugin.getId()}' plugin must be bound to a target route. See https://backstage.io/link?bind-routes for details.`);
+      }
+    }
+  }
+}
 
 const AppContext = createVersionedContext("app-context");
 const AppContextProvider = ({
@@ -2187,8 +2082,16 @@ function logDeprecation(thing) {
   console.warn(`WARNING: Call to ${thing} is deprecated and will break in the future`);
 }
 class AppIdentityProxy {
+  constructor() {
+    this.resolveTarget = () => {
+    };
+    this.waitForTarget = new Promise((resolve) => {
+      this.resolveTarget = resolve;
+    });
+  }
   setTarget(identityApi) {
     this.target = identityApi;
+    this.resolveTarget(identityApi);
   }
   getUserId() {
     if (!this.target) {
@@ -2211,42 +2114,29 @@ class AppIdentityProxy {
     return this.target.getProfile();
   }
   async getProfileInfo() {
-    if (!this.target) {
-      throw mkError("getProfileInfo");
-    }
-    return this.target.getProfileInfo();
+    return this.waitForTarget.then((target) => target.getProfileInfo());
   }
   async getBackstageIdentity() {
-    if (!this.target) {
-      throw mkError("getBackstageIdentity");
-    }
-    const identity = await this.target.getBackstageIdentity();
+    const identity = await this.waitForTarget.then((target) => target.getBackstageIdentity());
     if (!identity.userEntityRef.match(/^.*:.*\/.*$/)) {
       console.warn(`WARNING: The App IdentityApi provided an invalid userEntityRef, '${identity.userEntityRef}'. It must be a full Entity Reference of the form '<kind>:<namespace>/<name>'.`);
     }
     return identity;
   }
   async getCredentials() {
-    if (!this.target) {
-      throw mkError("getCredentials");
-    }
-    return this.target.getCredentials();
+    return this.waitForTarget.then((target) => target.getCredentials());
   }
   async getIdToken() {
-    if (!this.target) {
-      throw mkError("getIdToken");
-    }
-    if (!this.target.getIdToken) {
-      throw new Error("IdentityApi does not implement getIdToken");
-    }
-    logDeprecation("getIdToken");
-    return this.target.getIdToken();
+    return this.waitForTarget.then((target) => {
+      if (!target.getIdToken) {
+        throw new Error("IdentityApi does not implement getIdToken");
+      }
+      logDeprecation("getIdToken");
+      return target.getIdToken();
+    });
   }
   async signOut() {
-    if (!this.target) {
-      throw mkError("signOut");
-    }
-    await this.target.signOut();
+    await this.waitForTarget.then((target) => target.signOut());
     location.reload();
   }
 }
@@ -2361,7 +2251,7 @@ class ApiRegistry {
   }
 }
 
-function generateBoundRoutes(bindRoutes) {
+function resolveRouteBindings(bindRoutes) {
   const result = /* @__PURE__ */ new Map();
   if (bindRoutes) {
     const bind = (externalRoutes, targetRoutes) => {
@@ -2382,6 +2272,7 @@ function generateBoundRoutes(bindRoutes) {
   }
   return result;
 }
+
 function getBasePath(configApi) {
   var _a;
   let { pathname } = new URL((_a = configApi.getOptionalString("app.baseUrl")) != null ? _a : "/", "http://dummy.dev");
@@ -2453,9 +2344,16 @@ class AppManager {
   }
   getProvider() {
     const appContext = new AppContextImpl(this);
+    let routesHaveBeenValidated = false;
     const Provider = ({ children }) => {
       const appThemeApi = useMemo(() => AppThemeSelector.createWithStorage(this.themes), []);
-      const { routePaths, routeParents, routeObjects, featureFlags } = useMemo(() => {
+      const {
+        routePaths,
+        routeParents,
+        routeObjects,
+        featureFlags,
+        routeBindings
+      } = useMemo(() => {
         const result = traverseElementTree({
           root: children,
           discoverers: [childDiscoverer, routeElementDiscoverer],
@@ -2467,12 +2365,19 @@ class AppManager {
             featureFlags: featureFlagCollector
           }
         });
-        validateRoutes(result.routePaths, result.routeParents);
         result.collectedPlugins.forEach((plugin) => this.plugins.add(plugin));
         this.verifyPlugins(this.plugins);
         this.getApiHolder();
-        return result;
+        return {
+          ...result,
+          routeBindings: resolveRouteBindings(this.bindRoutes)
+        };
       }, [children]);
+      if (!routesHaveBeenValidated) {
+        routesHaveBeenValidated = true;
+        validateRouteParameters(routePaths, routeParents);
+        validateRouteBindings(routeBindings, this.plugins);
+      }
       const loadedConfig = useConfigLoader(this.configLoader, this.components, appThemeApi);
       const hasConfigApi = "api" in loadedConfig;
       if (hasConfigApi) {
@@ -2518,7 +2423,7 @@ class AppManager {
         routePaths,
         routeParents,
         routeObjects,
-        routeBindings: generateBoundRoutes(this.bindRoutes),
+        routeBindings,
         basePath: getBasePath(loadedConfig.api)
       }, children))));
     };