Skip to content

Latest commit

 

History

History
707 lines (639 loc) · 17.8 KB

report.api.md

File metadata and controls

707 lines (639 loc) · 17.8 KB

API Report File for "@backstage/plugin-auth-node"

Do not edit this file. It is a report generated by API Extractor.

import { BackstageIdentityResponse as BackstageIdentityResponse_2 } from '@backstage/plugin-auth-node';
import { BackstageSignInResult as BackstageSignInResult_2 } from '@backstage/plugin-auth-node';
import { Config } from '@backstage/config';
import { DiscoveryService } from '@backstage/backend-plugin-api';
import { Entity } from '@backstage/catalog-model';
import { EntityFilterQuery } from '@backstage/catalog-client';
import express from 'express';
import { ExtensionPoint } from '@backstage/backend-plugin-api';
import { JsonObject } from '@backstage/types';
import { JsonValue } from '@backstage/types';
import { LoggerService } from '@backstage/backend-plugin-api';
import { Profile } from 'passport';
import { Request as Request_2 } from 'express';
import { Response as Response_2 } from 'express';
import { Strategy } from 'passport';
import { ZodSchema } from 'zod';
import { ZodTypeDef } from 'zod';

// @public (undocumented)
export interface AuthOwnershipResolutionExtensionPoint {
  // (undocumented)
  setAuthOwnershipResolver(ownershipResolver: AuthOwnershipResolver): void;
}

// @public (undocumented)
export const authOwnershipResolutionExtensionPoint: ExtensionPoint<AuthOwnershipResolutionExtensionPoint>;

// @public
export interface AuthOwnershipResolver {
  // (undocumented)
  resolveOwnershipEntityRefs(entity: Entity): Promise<{
    ownershipEntityRefs: string[];
  }>;
}

// @public @deprecated (undocumented)
export type AuthProviderConfig = {
  baseUrl: string;
  appUrl: string;
  isOriginAllowed: (origin: string) => boolean;
  cookieConfigurer?: CookieConfigurer;
};

// @public (undocumented)
export type AuthProviderFactory = (options: {
  providerId: string;
  globalConfig: AuthProviderConfig;
  config: Config;
  logger: LoggerService;
  resolverContext: AuthResolverContext;
  baseUrl: string;
  appUrl: string;
  isOriginAllowed: (origin: string) => boolean;
  cookieConfigurer?: CookieConfigurer;
}) => AuthProviderRouteHandlers;

// @public (undocumented)
export interface AuthProviderRegistrationOptions {
  // (undocumented)
  factory: AuthProviderFactory;
  // (undocumented)
  providerId: string;
}

// @public
export interface AuthProviderRouteHandlers {
  frameHandler(req: Request_2, res: Response_2): Promise<void>;
  logout?(req: Request_2, res: Response_2): Promise<void>;
  refresh?(req: Request_2, res: Response_2): Promise<void>;
  start(req: Request_2, res: Response_2): Promise<void>;
}

// @public (undocumented)
export interface AuthProvidersExtensionPoint {
  // (undocumented)
  registerProvider(options: AuthProviderRegistrationOptions): void;
}

// @public (undocumented)
export const authProvidersExtensionPoint: ExtensionPoint<AuthProvidersExtensionPoint>;

// @public
export type AuthResolverCatalogUserQuery =
  | {
      entityRef:
        | string
        | {
            kind?: string;
            namespace?: string;
            name: string;
          };
    }
  | {
      annotations: Record<string, string>;
    }
  | {
      filter: EntityFilterQuery;
    };

// @public
export type AuthResolverContext = {
  issueToken(params: TokenParams): Promise<{
    token: string;
  }>;
  findCatalogUser(query: AuthResolverCatalogUserQuery): Promise<{
    entity: Entity;
  }>;
  signInWithCatalogUser(
    query: AuthResolverCatalogUserQuery,
  ): Promise<BackstageSignInResult>;
  resolveOwnershipEntityRefs(entity: Entity): Promise<{
    ownershipEntityRefs: string[];
  }>;
};

// @public
export interface BackstageIdentityResponse extends BackstageSignInResult {
  expiresInSeconds?: number;
  identity: BackstageUserIdentity;
}

// @public
export interface BackstageSignInResult {
  token: string;
}

// @public
export type BackstageUserIdentity = {
  type: 'user';
  userEntityRef: string;
  ownershipEntityRefs: string[];
};

// @public (undocumented)
export type ClientAuthResponse<TProviderInfo> = {
  providerInfo: TProviderInfo;
  profile: ProfileInfo;
  backstageIdentity?: BackstageIdentityResponse;
};

// @public
export namespace commonSignInResolvers {
  const emailMatchingUserEntityProfileEmail: SignInResolverFactory<
    unknown,
    unknown
  >;
  const emailLocalPartMatchingUserEntityName: SignInResolverFactory<
    unknown,
    | {
        allowedDomains?: string[] | undefined;
      }
    | undefined
  >;
}

// @public
export type CookieConfigurer = (ctx: {
  providerId: string;
  baseUrl: string;
  callbackUrl: string;
  appOrigin: string;
}) => {
  domain: string;
  path: string;
  secure: boolean;
  sameSite?: 'none' | 'lax' | 'strict';
};

// @public (undocumented)
export function createOAuthAuthenticator<TContext, TProfile>(
  authenticator: OAuthAuthenticator<TContext, TProfile>,
): OAuthAuthenticator<TContext, TProfile>;

// @public (undocumented)
export function createOAuthProviderFactory<TProfile>(options: {
  authenticator: OAuthAuthenticator<unknown, TProfile>;
  additionalScopes?: string[];
  stateTransform?: OAuthStateTransform;
  profileTransform?: ProfileTransform<OAuthAuthenticatorResult<TProfile>>;
  signInResolver?: SignInResolver<OAuthAuthenticatorResult<TProfile>>;
  signInResolverFactories?: {
    [name in string]: SignInResolverFactory;
  };
}): AuthProviderFactory;

// @public (undocumented)
export function createOAuthRouteHandlers<TProfile>(
  options: OAuthRouteHandlersOptions<TProfile>,
): AuthProviderRouteHandlers;

// @public (undocumented)
export function createProxyAuthenticator<TContext, TResult, TProviderInfo>(
  authenticator: ProxyAuthenticator<TContext, TResult, TProviderInfo>,
): ProxyAuthenticator<TContext, TResult, TProviderInfo>;

// @public (undocumented)
export function createProxyAuthProviderFactory<TResult>(options: {
  authenticator: ProxyAuthenticator<unknown, TResult, unknown>;
  profileTransform?: ProfileTransform<TResult>;
  signInResolver?: SignInResolver<TResult>;
  signInResolverFactories?: Record<string, SignInResolverFactory>;
}): AuthProviderFactory;

// @public (undocumented)
export function createProxyAuthRouteHandlers<TResult>(
  options: ProxyAuthRouteHandlersOptions<TResult>,
): AuthProviderRouteHandlers;

// @public (undocumented)
export function createSignInResolverFactory<
  TAuthResult,
  TOptionsOutput,
  TOptionsInput,
>(
  options: SignInResolverFactoryOptions<
    TAuthResult,
    TOptionsOutput,
    TOptionsInput
  >,
): SignInResolverFactory<TAuthResult, TOptionsInput>;

// @public (undocumented)
export function decodeOAuthState(encodedState: string): OAuthState;

// @public
export class DefaultIdentityClient implements IdentityApi {
  // @deprecated
  authenticate(token: string | undefined): Promise<BackstageIdentityResponse>;
  static create(options: IdentityClientOptions): DefaultIdentityClient;
  // (undocumented)
  getIdentity(
    options: IdentityApiGetIdentityRequest,
  ): Promise<BackstageIdentityResponse | undefined>;
}

// @public (undocumented)
export function encodeOAuthState(state: OAuthState): string;

// @public @deprecated
export function getBearerTokenFromAuthorizationHeader(
  authorizationHeader: unknown,
): string | undefined;

// @public
export interface IdentityApi {
  getIdentity(
    options: IdentityApiGetIdentityRequest,
  ): Promise<BackstageIdentityResponse | undefined>;
}

// @public
export type IdentityApiGetIdentityRequest = {
  request: Request_2<unknown>;
};

// @public @deprecated
export class IdentityClient {
  // @deprecated
  authenticate(token: string | undefined): Promise<BackstageIdentityResponse>;
  // (undocumented)
  static create(options: IdentityClientOptions): IdentityClient;
}

// @public
export type IdentityClientOptions = {
  discovery: DiscoveryService;
  issuer?: string;
  algorithms?: string[];
};

// @public (undocumented)
export interface OAuthAuthenticator<TContext, TProfile> {
  // (undocumented)
  authenticate(
    input: OAuthAuthenticatorAuthenticateInput,
    ctx: TContext,
  ): Promise<OAuthAuthenticatorResult<TProfile>>;
  // (undocumented)
  defaultProfileTransform: ProfileTransform<OAuthAuthenticatorResult<TProfile>>;
  // (undocumented)
  initialize(ctx: { callbackUrl: string; config: Config }): TContext;
  // (undocumented)
  logout?(input: OAuthAuthenticatorLogoutInput, ctx: TContext): Promise<void>;
  // (undocumented)
  refresh(
    input: OAuthAuthenticatorRefreshInput,
    ctx: TContext,
  ): Promise<OAuthAuthenticatorResult<TProfile>>;
  // (undocumented)
  scopes?: OAuthAuthenticatorScopeOptions;
  // @deprecated (undocumented)
  shouldPersistScopes?: boolean;
  // (undocumented)
  start(
    input: OAuthAuthenticatorStartInput,
    ctx: TContext,
  ): Promise<{
    url: string;
    status?: number;
  }>;
}

// @public (undocumented)
export interface OAuthAuthenticatorAuthenticateInput {
  // (undocumented)
  req: Request_2;
}

// @public (undocumented)
export interface OAuthAuthenticatorLogoutInput {
  // (undocumented)
  accessToken?: string;
  // (undocumented)
  refreshToken?: string;
  // (undocumented)
  req: Request_2;
}

// @public (undocumented)
export interface OAuthAuthenticatorRefreshInput {
  // (undocumented)
  refreshToken: string;
  // (undocumented)
  req: Request_2;
  // (undocumented)
  scope: string;
  scopeAlreadyGranted?: boolean;
}

// @public (undocumented)
export interface OAuthAuthenticatorResult<TProfile> {
  // (undocumented)
  fullProfile: TProfile;
  // (undocumented)
  session: OAuthSession;
}

// @public (undocumented)
export interface OAuthAuthenticatorScopeOptions {
  // (undocumented)
  persist?: boolean;
  // (undocumented)
  required?: string[];
  // (undocumented)
  transform?: (options: {
    requested: Iterable<string>;
    granted: Iterable<string>;
    required: Iterable<string>;
    additional: Iterable<string>;
  }) => Iterable<string>;
}

// @public (undocumented)
export interface OAuthAuthenticatorStartInput {
  // (undocumented)
  req: Request_2;
  // (undocumented)
  scope: string;
  // (undocumented)
  state: string;
}

// @public (undocumented)
export class OAuthEnvironmentHandler implements AuthProviderRouteHandlers {
  constructor(handlers: Map<string, AuthProviderRouteHandlers>);
  // (undocumented)
  frameHandler(req: express.Request, res: express.Response): Promise<void>;
  // (undocumented)
  logout(req: express.Request, res: express.Response): Promise<void>;
  // (undocumented)
  static mapConfig(
    config: Config,
    factoryFunc: (envConfig: Config) => AuthProviderRouteHandlers,
  ): OAuthEnvironmentHandler;
  // (undocumented)
  refresh(req: express.Request, res: express.Response): Promise<void>;
  // (undocumented)
  start(req: express.Request, res: express.Response): Promise<void>;
}

// @public (undocumented)
export interface OAuthRouteHandlersOptions<TProfile> {
  // (undocumented)
  additionalScopes?: string[];
  // (undocumented)
  appUrl: string;
  // (undocumented)
  authenticator: OAuthAuthenticator<any, TProfile>;
  // (undocumented)
  baseUrl: string;
  // (undocumented)
  config: Config;
  // (undocumented)
  cookieConfigurer?: CookieConfigurer;
  // (undocumented)
  isOriginAllowed: (origin: string) => boolean;
  // (undocumented)
  profileTransform?: ProfileTransform<OAuthAuthenticatorResult<TProfile>>;
  // (undocumented)
  providerId: string;
  // (undocumented)
  resolverContext: AuthResolverContext;
  // (undocumented)
  signInResolver?: SignInResolver<OAuthAuthenticatorResult<TProfile>>;
  // (undocumented)
  stateTransform?: OAuthStateTransform;
}

// @public (undocumented)
export interface OAuthSession {
  // (undocumented)
  accessToken: string;
  // (undocumented)
  expiresInSeconds?: number;
  // (undocumented)
  idToken?: string;
  // (undocumented)
  refreshToken?: string;
  // (undocumented)
  refreshTokenExpiresInSeconds?: number;
  // (undocumented)
  scope: string;
  // (undocumented)
  tokenType: string;
}

// @public
export type OAuthState = {
  nonce: string;
  env: string;
  origin?: string;
  scope?: string;
  redirectUrl?: string;
  flow?: string;
  audience?: string;
};

// @public (undocumented)
export type OAuthStateTransform = (
  state: OAuthState,
  context: {
    req: Request_2;
  },
) => Promise<{
  state: OAuthState;
}>;

// @public (undocumented)
export type PassportDoneCallback<TResult, TPrivateInfo = never> = (
  err?: Error,
  result?: TResult,
  privateInfo?: TPrivateInfo,
) => void;

// @public (undocumented)
export class PassportHelpers {
  // (undocumented)
  static executeFetchUserProfileStrategy(
    providerStrategy: Strategy,
    accessToken: string,
  ): Promise<PassportProfile>;
  // (undocumented)
  static executeFrameHandlerStrategy<TResult, TPrivateInfo = never>(
    req: Request_2,
    providerStrategy: Strategy,
    options?: Record<string, string>,
  ): Promise<{
    result: TResult;
    privateInfo: TPrivateInfo;
  }>;
  // (undocumented)
  static executeRedirectStrategy(
    req: Request_2,
    providerStrategy: Strategy,
    options: Record<string, string>,
  ): Promise<{
    url: string;
    status?: number;
  }>;
  // (undocumented)
  static executeRefreshTokenStrategy(
    providerStrategy: Strategy,
    refreshToken: string,
    scope: string,
  ): Promise<{
    accessToken: string;
    refreshToken?: string;
    params: any;
  }>;
  // (undocumented)
  static transformProfile: (
    profile: PassportProfile,
    idToken?: string,
  ) => ProfileInfo;
}

// @public (undocumented)
export class PassportOAuthAuthenticatorHelper {
  // (undocumented)
  authenticate(
    input: OAuthAuthenticatorAuthenticateInput,
    options?: Record<string, string>,
  ): Promise<OAuthAuthenticatorResult<PassportProfile>>;
  // (undocumented)
  static defaultProfileTransform: ProfileTransform<
    OAuthAuthenticatorResult<PassportProfile>
  >;
  // (undocumented)
  fetchProfile(accessToken: string): Promise<PassportProfile>;
  // (undocumented)
  static from(strategy: Strategy): PassportOAuthAuthenticatorHelper;
  // (undocumented)
  refresh(
    input: OAuthAuthenticatorRefreshInput,
  ): Promise<OAuthAuthenticatorResult<PassportProfile>>;
  // (undocumented)
  start(
    input: OAuthAuthenticatorStartInput,
    options: Record<string, string>,
  ): Promise<{
    url: string;
    status?: number;
  }>;
}

// @public (undocumented)
export type PassportOAuthDoneCallback = PassportDoneCallback<
  PassportOAuthResult,
  PassportOAuthPrivateInfo
>;

// @public (undocumented)
export type PassportOAuthPrivateInfo = {
  refreshToken?: string;
};

// @public (undocumented)
export type PassportOAuthResult = {
  fullProfile: PassportProfile;
  params: {
    id_token?: string;
    scope: string;
    token_type?: string;
    expires_in: number;
  };
  accessToken: string;
};

// @public (undocumented)
export type PassportProfile = Profile & {
  avatarUrl?: string;
  email?: string;
  photo?: string;
};

// @public
export function prepareBackstageIdentityResponse(
  result: BackstageSignInResult_2,
): BackstageIdentityResponse_2;

// @public
export type ProfileInfo = {
  email?: string;
  displayName?: string;
  picture?: string;
};

// @public
export type ProfileTransform<TResult> = (
  result: TResult,
  context: AuthResolverContext,
) => Promise<{
  profile: ProfileInfo;
}>;

// @public (undocumented)
export interface ProxyAuthenticator<
  TContext,
  TResult,
  TProviderInfo = undefined,
> {
  // (undocumented)
  authenticate(
    options: {
      req: Request_2;
    },
    ctx: TContext,
  ): Promise<{
    result: TResult;
    providerInfo?: TProviderInfo;
  }>;
  // (undocumented)
  defaultProfileTransform: ProfileTransform<TResult>;
  // (undocumented)
  initialize(ctx: { config: Config }): TContext;
}

// @public (undocumented)
export interface ProxyAuthRouteHandlersOptions<TResult> {
  // (undocumented)
  authenticator: ProxyAuthenticator<any, TResult, unknown>;
  // (undocumented)
  config: Config;
  // (undocumented)
  profileTransform?: ProfileTransform<TResult>;
  // (undocumented)
  resolverContext: AuthResolverContext;
  // (undocumented)
  signInResolver: SignInResolver<TResult>;
}

// @public (undocumented)
export function readDeclarativeSignInResolver<TAuthResult>(
  options: ReadDeclarativeSignInResolverOptions<TAuthResult>,
): SignInResolver<TAuthResult> | undefined;

// @public (undocumented)
export interface ReadDeclarativeSignInResolverOptions<TAuthResult> {
  // (undocumented)
  config: Config;
  // (undocumented)
  signInResolverFactories: {
    [name in string]: SignInResolverFactory<TAuthResult, unknown>;
  };
}

// @public (undocumented)
export function sendWebMessageResponse(
  res: Response_2,
  appOrigin: string,
  response: WebMessageResponse,
): void;

// @public
export type SignInInfo<TAuthResult> = {
  profile: ProfileInfo;
  result: TAuthResult;
};

// @public
export type SignInResolver<TAuthResult> = (
  info: SignInInfo<TAuthResult>,
  context: AuthResolverContext,
) => Promise<BackstageSignInResult>;

// @public (undocumented)
export interface SignInResolverFactory<TAuthResult = any, TOptions = any> {
  // (undocumented)
  (
    ...options: undefined extends TOptions
      ? [options?: TOptions]
      : [options: TOptions]
  ): SignInResolver<TAuthResult>;
  // (undocumented)
  optionsJsonSchema?: JsonObject;
}

// @public (undocumented)
export interface SignInResolverFactoryOptions<
  TAuthResult,
  TOptionsOutput,
  TOptionsInput,
> {
  // (undocumented)
  create(options: TOptionsOutput): SignInResolver<TAuthResult>;
  // (undocumented)
  optionsSchema?: ZodSchema<TOptionsOutput, ZodTypeDef, TOptionsInput>;
}

// @public
export type TokenParams = {
  claims: {
    sub: string;
    ent?: string[];
  } & Record<string, JsonValue>;
};

// @public
export const tokenTypes: Readonly<{
  user: Readonly<{
    typParam: 'vnd.backstage.user';
    audClaim: 'backstage';
  }>;
  limitedUser: Readonly<{
    typParam: 'vnd.backstage.limited-user';
  }>;
  plugin: Readonly<{
    typParam: 'vnd.backstage.plugin';
  }>;
}>;

// @public
export type WebMessageResponse =
  | {
      type: 'authorization_response';
      response: ClientAuthResponse<unknown>;
    }
  | {
      type: 'authorization_response';
      error: Error;
    };