@herrromich/az-functions 1.0.0

package/src/http-controller/security/authenticator.provider.ts

@@ -0,0 +1,238 @@
+import { HttpRequest } from '@azure/functions';
+import { inject, injectable } from 'inversify';
+import { LOGGER_FACTORY, LoggerFactory } from 'logger';
+import { AuthContext, AuthenticationError, Principal } from 'security';
+import { ForbiddenError, UnauthorizedError } from '../http-controller.model';
+import { HttpOperationRegistration } from '../http-operations-registration.service';
+import {
+  OperationAuthenticationResolver,
+  SecurityBinding,
+  SecurityBindingObject,
+} from './operation-authentication.resolver';
+import { FallbackPrincipalMergeService } from './principal-merge.service';
+
+interface BaseAuthenticationResult {
+  state: string;
+  scheme: string;
+}
+
+interface SuccessfulAuthenticationResult extends BaseAuthenticationResult {
+  state: 'successful';
+  principal: Principal;
+}
+
+interface FailedAuthenticationResult extends BaseAuthenticationResult {
+  state: 'unauthenticated' | 'unauthorized';
+  error: unknown;
+}
+
+export type AuthenticationResult = SuccessfulAuthenticationResult | FailedAuthenticationResult;
+
+interface BaseAndAuthenticationResult {
+  authentications: AuthenticationResult[];
+}
+
+interface SuccessfulAndAuthenticationResult extends BaseAndAuthenticationResult {
+  state: 'successful';
+  authContext: AuthContext;
+}
+
+interface FailedAndAuthenticationResult extends BaseAndAuthenticationResult {
+  state: 'unauthenticated' | 'unauthorized';
+}
+
+interface SkippedAndAuthenticationResult {
+  state: 'skipped';
+  authentications: {
+    scheme: string;
+    state: 'skipped';
+  }[];
+}
+
+type AndAuthenticationResult = SuccessfulAndAuthenticationResult | FailedAndAuthenticationResult;
+type AndAuthenticationResults = (AndAuthenticationResult | SkippedAndAuthenticationResult)[];
+
+interface AuthenticationResultsByState {
+  successful: SuccessfulAuthenticationResult[];
+  unauthenticated: FailedAuthenticationResult[];
+  unauthorized: FailedAuthenticationResult[];
+}
+
+export type AuthenticationHandler = (request: HttpRequest) => Promise<AuthContext>;
+
+@injectable()
+export class AuthenticatorProvider {
+  private readonly logger;
+
+  constructor(
+    @inject(LOGGER_FACTORY) loggerFactory: LoggerFactory,
+    private readonly operationAuthenticationResolver: OperationAuthenticationResolver,
+    private readonly principalMergeService: FallbackPrincipalMergeService,
+  ) {
+    this.logger = loggerFactory();
+  }
+
+  provideAuthenticator(registrationData: HttpOperationRegistration): AuthenticationHandler {
+    const { operationId } = registrationData;
+    const securityBindings = this.operationAuthenticationResolver.getOperationSecurityBindings(registrationData);
+    if (securityBindings.length === 0) {
+      this.logger.info(`No authentication required for operation id=${operationId}.`);
+      this.logger.debug(`No authentication required for operation id=${operationId}.`, {
+        registrationData,
+      });
+      return this.operationAuthenticationResolver.defaultAuthenticator(registrationData);
+    }
+    this.logger.info(`Authentication required for operation id=${operationId}.`);
+    this.logger.debug(`Authentication required for operation id=${operationId}.`, {
+      operationId,
+      security: securityBindings,
+      registrationData,
+    });
+    return async (request): Promise<AuthContext> => {
+      return await this.authenticate(operationId, securityBindings, request);
+    };
+  }
+
+  private async authenticate(
+    operationId: string,
+    securityBindings: SecurityBindingObject[],
+    request: HttpRequest,
+  ): Promise<AuthContext> {
+    this.logger.info(`Authenticating request for operation id=${operationId}.`);
+    this.logger.debug(`Authenticating request for operation id=${operationId}.`, {
+      operationId,
+      security: securityBindings,
+      request,
+    });
+
+    let andAuthenticationResult: AndAuthenticationResult = {
+      state: 'unauthenticated',
+      authentications: [],
+    };
+    const andAuthenticationResults: AndAuthenticationResults = [];
+
+    for (const securityBinding of securityBindings) {
+      if (andAuthenticationResult.state === 'unauthenticated') {
+        const authenticationResults = await Promise.all(
+          Object.entries(securityBinding).map(
+            async ([scheme, binding]): Promise<AuthenticationResult> =>
+              await this.authenticateSecurityBinding(operationId, scheme, binding, request),
+          ),
+        );
+
+        andAuthenticationResult = this.getAndAuthenticationResult(authenticationResults);
+        andAuthenticationResults.push(andAuthenticationResult);
+      } else {
+        andAuthenticationResults.push({
+          state: 'skipped',
+          authentications: Object.keys(securityBinding).map(scheme => ({
+            scheme,
+            state: 'skipped',
+          })),
+        });
+      }
+    }
+    const details = {
+      operationId,
+      authentications: andAuthenticationResults,
+    };
+    switch (andAuthenticationResult.state) {
+      case 'successful':
+        this.logger.info(`Authentication successful for operation id=${operationId}`);
+        this.logger.debug(`Authentication successful for operation id=${operationId}`, details);
+        return andAuthenticationResult.authContext;
+      case 'unauthenticated':
+        throw new UnauthorizedError('Authentication failed', { details });
+      case 'unauthorized':
+        throw new ForbiddenError('Authorization failed', { details });
+    }
+  }
+
+  private async authenticateSecurityBinding(
+    operationId: string,
+    scheme: string,
+    binding: SecurityBinding,
+    request: HttpRequest,
+  ): Promise<AuthenticationResult> {
+    const { authService, scopes } = binding;
+    try {
+      const principal = await authService.authenticate(request);
+      if (scopes.some(scope => !principal.scopes.includes(scope))) {
+        this.logger.silly(
+          `Identity does not have required scopes for scheme=${scheme} in operation id=${operationId}`,
+          {
+            operationId,
+            scheme,
+            requiredScopes: scopes,
+            principalScopes: principal.scopes,
+          },
+        );
+        return {
+          scheme,
+          state: 'unauthorized',
+          error: new UnauthorizedError(`Identity does not have required scopes for scheme=${scheme}`, {
+            details: {
+              scheme,
+              requiredScopes: scopes,
+              principalScopes: principal.scopes,
+            },
+          }),
+        };
+      } else {
+        return {
+          scheme,
+          principal,
+          state: 'successful',
+        };
+      }
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        this.logger.silly(`Authentication failed for scheme=${scheme} in operation id=${operationId}`, {
+          operationId,
+          scheme,
+          error,
+        });
+        return {
+          scheme,
+          state: 'unauthenticated',
+          error,
+        };
+      }
+      throw error;
+    }
+  }
+
+  private getAndAuthenticationResult(authenticationResults: AuthenticationResult[]): AndAuthenticationResult {
+    const resultsByState = authenticationResults.reduce<AuthenticationResultsByState>(
+      (acc, result) => {
+        switch (result.state) {
+          case 'successful':
+            acc.successful.push(result);
+            break;
+          case 'unauthorized':
+            acc.unauthorized.push(result);
+            break;
+          case 'unauthenticated':
+            acc.unauthenticated.push(result);
+            break;
+        }
+        return acc;
+      },
+      {
+        successful: [],
+        unauthorized: [],
+        unauthenticated: [],
+      },
+    );
+    if (resultsByState.unauthorized.length > 0) {
+      return { state: 'unauthorized', authentications: authenticationResults };
+    } else if (resultsByState.unauthenticated.length > 0) {
+      return { state: 'unauthenticated', authentications: authenticationResults };
+    } else {
+      const authContext = this.principalMergeService.mergePrincipals(
+        resultsByState.successful.map(result => result.principal),
+      );
+      return { state: 'successful', authContext, authentications: authenticationResults };
+    }
+  }
+}

package/src/http-controller/security/bearer-security-authentication.service.ts

@@ -0,0 +1,16 @@
+import { HttpRequest } from '@azure/functions';
+import { AuthenticationError, Principal } from 'security';
+import { AuthenticationService } from './authentication-service';
+import { BearerTokenService } from './bearer-token.service';
+
+export class BearerSecurityAuthenticationService implements AuthenticationService {
+  constructor(private readonly bearerTokenService: BearerTokenService) {}
+
+  async authenticate(request: HttpRequest): Promise<Principal> {
+    const [bearerHeader, bearerToken] = request.headers.get('Authorization')?.split(' ') ?? [];
+    if (bearerHeader !== 'Bearer' || !bearerToken) {
+      throw new AuthenticationError('No Bearer token in Authorization header.');
+    }
+    return this.bearerTokenService.getPrincipalFromToken(bearerToken);
+  }
+}

package/src/http-controller/security/bearer-token.service.ts

@@ -0,0 +1,6 @@
+import { Principal } from 'security';
+
+export interface BearerTokenService {
+  readonly bearerFormat: string;
+  getPrincipalFromToken(accessToken: string): Principal | PromiseLike<Principal>;
+}

package/src/http-controller/security/index.ts

@@ -0,0 +1,3 @@
+export * from './authentication-service';
+export * from './bearer-security-authentication.service';
+export * from './bearer-token.service';

package/src/http-controller/security/operation-authentication.resolver.ts

@@ -0,0 +1,111 @@
+import { RestApplication } from 'http-controller';
+import { Container, inject, injectable } from 'inversify';
+import { LOGGER_FACTORY, LoggerFactory } from 'logger';
+import { SecurityRequirementObject } from 'openapi3-ts/oas30';
+import { PLATFORM_CONTAINER } from 'shared';
+import { HttpTriggerDefinitionError } from '../http-handler-support.factory';
+import { HttpOperationRegistration } from '../http-operations-registration.service';
+import { AUTHENTICATION_SERVICE, AuthenticationService, REST_APPLICATION_TAG_KEY } from './authentication-service';
+import { AuthenticationHandler } from './authenticator.provider';
+
+export interface SecurityBinding {
+  authService: AuthenticationService;
+  scopes: string[];
+}
+
+export type SecurityBindingObject = Record<string, SecurityBinding>;
+
+@injectable()
+export class OperationAuthenticationResolver {
+  private readonly logger;
+
+  constructor(
+    @inject(LOGGER_FACTORY) loggerFactory: LoggerFactory,
+    @inject(PLATFORM_CONTAINER) private readonly platformContainer: Container,
+  ) {
+    this.logger = loggerFactory();
+  }
+
+  getOperationSecurityBindings(registrationData: HttpOperationRegistration): SecurityBindingObject[] {
+    const { operationId, application, operationMetadata } = registrationData;
+    let security: SecurityRequirementObject[] = [];
+    if (operationMetadata.security !== undefined) {
+      this.logger.debug(`Found direct security schemes for operation ${operationId}`, {
+        security,
+      });
+      security = operationMetadata.security;
+    } else if (application.openApiConfig.security !== undefined) {
+      this.logger.debug(
+        `No direct security schemes found for operation ${operationId}. Using application-level security schemes`,
+        {
+          applicationName: application.name,
+          security,
+        },
+      );
+      security = application.openApiConfig.security;
+    } else {
+      this.logger.debug(`No security schemes found for operation ${operationId}`, {
+        operationId,
+        applicationName: application.name,
+      });
+      security = [];
+    }
+    return this.getSecurityBindingObjects(operationId, application, security);
+  }
+
+  private getSecurityBindingObjects(
+    operationId: string,
+    application: RestApplication,
+    security: SecurityRequirementObject[],
+  ) {
+    const securitySchemes = application.openApiConfig.components?.securitySchemes ?? {};
+    return security.map(requirement => {
+      return Object.entries(requirement).reduce<SecurityBindingObject>((bindings, [scheme, scopes]) => {
+        const securityScheme = securitySchemes[scheme];
+        if (securityScheme === undefined) {
+          throw new HttpTriggerDefinitionError(
+            `Security scheme ${scheme} not found in application ${application.name} for operation ${operationId}`,
+            {
+              details: {
+                operationId,
+                applicationName: application.name,
+                securityScheme: scheme,
+                securitySchemes,
+              },
+            },
+          );
+        }
+        const authenticationService = this.platformContainer.get(AUTHENTICATION_SERVICE, {
+          name: scheme,
+          tag: {
+            key: REST_APPLICATION_TAG_KEY,
+            value: application.name,
+          },
+          optional: true,
+        });
+        if (authenticationService === undefined) {
+          throw new HttpTriggerDefinitionError(
+            `Failed resolving authentication service for scheme ${scheme} in application ${application.name}`,
+          );
+        }
+        bindings[scheme] = {
+          authService: authenticationService,
+          scopes,
+        };
+        return bindings;
+      }, {});
+    });
+  }
+
+  defaultAuthenticator(registrationData: HttpOperationRegistration): AuthenticationHandler {
+    const { operationId } = registrationData;
+    return async () => {
+      this.logger.info(`No security schemes configured for operation ${operationId}`);
+      return {
+        principal: null,
+        principals: [],
+        scopes: [],
+      };
+    };
+  }
+}

package/src/http-controller/security/principal-merge.service.ts

@@ -0,0 +1,26 @@
+import { inject, injectable, optional } from 'inversify';
+import { AuthContext, Principal } from 'security';
+import { serviceIdentifier } from 'shared';
+import { StrictPrincipalMergeService } from './strict-principal-merge.servce';
+
+export const PRINCIPAL_MERGE_SERVICE = serviceIdentifier<PrincipalMergeService>('AzFunctions.PrincipalMergeService');
+
+export interface PrincipalMergeService {
+  mergePrincipals(principals: Principal[]): AuthContext;
+}
+
+@injectable()
+export class FallbackPrincipalMergeService implements PrincipalMergeService {
+  private readonly mergeService;
+
+  constructor(
+    defaultMergeService: StrictPrincipalMergeService,
+    @inject(PRINCIPAL_MERGE_SERVICE) @optional() optionalMergeService: PrincipalMergeService | undefined,
+  ) {
+    this.mergeService = optionalMergeService ?? defaultMergeService;
+  }
+
+  mergePrincipals(principals: Principal[]): AuthContext {
+    return this.mergeService.mergePrincipals(principals);
+  }
+}

package/src/http-controller/security/strict-principal-merge.servce.ts

@@ -0,0 +1,23 @@
+import { injectable } from 'inversify';
+import { AuthContext, AuthenticationError, Principal } from 'security';
+import { PrincipalMergeService } from './principal-merge.service';
+
+@injectable()
+export class StrictPrincipalMergeService implements PrincipalMergeService {
+  mergePrincipals(principals: Principal[]): AuthContext {
+    const firstPrincipal = principals[0] ?? null;
+    const principalScopes = new Set(firstPrincipal?.scopes ?? []);
+    for (const principal of principals) {
+      if (principal.subject !== firstPrincipal?.subject || principal.type !== firstPrincipal?.type) {
+        throw new AuthenticationError('AuthContext subject or type mismatch during merge', {
+          details: {
+            firstPrincipal,
+            principal,
+          },
+        });
+      }
+      principal.scopes.forEach(scope => principalScopes.add(scope));
+    }
+    return { principal: firstPrincipal, principals: principals, scopes: Array.from(principalScopes) };
+  }
+}

package/src/http-controller/swagger-handling.service.ts

@@ -0,0 +1,126 @@
+import { HttpRequest, HttpResponseInit } from '@azure/functions';
+import { StatusCodes } from 'http-status-codes';
+import { inject, injectable } from 'inversify';
+import * as mime from 'mime-types';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { OpenAPIObject } from 'openapi3-ts/oas30';
+import { BASE_DIR } from 'shared';
+import { OpenApiDefinitionError, OpenApiDefinitionService } from './open-api-definition.service';
+
+@injectable()
+export class SwaggerHandlingService {
+  constructor(
+    @inject(BASE_DIR) private readonly baseDir: string,
+    private readonly openApiDefinitionService: OpenApiDefinitionService,
+  ) {}
+
+  public async handleSwaggerContent(request: HttpRequest): Promise<HttpResponseInit> {
+    const rawUrl = this.getOriginalUrl(request);
+    const filename = request.params['fileName'];
+    if (filename === undefined) {
+      const divider = rawUrl.endsWith('/') ? '' : '/';
+      return {
+        status: StatusCodes.MOVED_TEMPORARILY,
+        headers: {
+          location: `${rawUrl}${divider}index.html`,
+        },
+      };
+    }
+    if (filename === 'swagger-initializer.js') {
+      const definitions = this.openApiDefinitionService.getApplications();
+      const primaryUrl = definitions[0] ?? '';
+      const urls = definitions.map(definitionName => ({
+        name: this.openApiDefinitionService.getApplication(definitionName).openApiConfig.info.title,
+        url: `./definition/${definitionName}`,
+      }));
+      const body = `
+window.onload = function () {
+  const ui = SwaggerUIBundle({
+    urls: ${JSON.stringify(urls)},
+    'urls.primaryName': '${primaryUrl}',
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+    plugins: [SwaggerUIBundle.plugins.DownloadUrl],
+    layout: 'StandaloneLayout',
+  });
+
+  ui.initOAuth({
+    clientId: 'bbce1dad-9aae-47c4-938e-adba5dd812ce',
+    scopes: 'user.read openid profile email offline_access',
+  });
+
+  window.ui = ui;
+};
+`;
+      return {
+        status: StatusCodes.OK,
+        body: body,
+        headers: {
+          ContentType: 'application/javascript',
+        },
+      };
+    } else {
+      return await this.serveSwaggerUi(filename);
+    }
+  }
+
+  private async serveSwaggerUi(fileName: string): Promise<HttpResponseInit> {
+    const buffer = await fs.readFile(path.join(this.baseDir, 'assets/swagger-ui', fileName)).catch(() => undefined);
+    if (!buffer) {
+      return {
+        status: StatusCodes.BAD_REQUEST,
+        body: 'Path parameter is unknown',
+      };
+    }
+    const contentType = mime.contentType(fileName);
+    return {
+      status: StatusCodes.OK,
+      body: buffer,
+      headers: {
+        ContentType: contentType || 'application/octet-stream',
+      },
+    };
+  }
+
+  handleOpenApiDefinition(request: HttpRequest): HttpResponseInit {
+    const rawUrl = this.getOriginalUrl(request);
+    const url = new URL(rawUrl);
+    const parts = url.pathname.split('/');
+    const definitionNamePart = parts.pop();
+    const definitionPart = parts.pop();
+    const specPart = parts.pop();
+    if (specPart !== 'spec' || definitionPart !== 'definition' || !definitionNamePart) {
+      return {
+        status: StatusCodes.BAD_REQUEST,
+        body: 'Bad request for api definition.',
+      };
+    }
+    let openAPIObject: OpenAPIObject;
+    try {
+      const apisUrl = `${url.origin}${parts.join('/')}`;
+      openAPIObject = this.openApiDefinitionService.generateDocument(definitionNamePart, apisUrl);
+    } catch (e: unknown) {
+      if (e instanceof OpenApiDefinitionError) {
+        return {
+          status: StatusCodes.NOT_FOUND,
+          body: `Definition name=${definitionNamePart} is not found.`,
+        };
+      } else {
+        return {
+          status: StatusCodes.INTERNAL_SERVER_ERROR,
+          body: `Cannot process definition name=${definitionNamePart}.`,
+        };
+      }
+    }
+    return {
+      status: 200,
+      jsonBody: openAPIObject,
+    };
+  }
+
+  private getOriginalUrl(request: HttpRequest) {
+    return request.headers.get('x-ms-original-url') ?? request.url;
+  }
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+import './init';
+
+export {
+  EventHubHandler,
+  EventHubHandlerCardinality,
+  EventHubMessageWrapper,
+  EventHubTriggerMessageArgConfig,
+  Message,
+  Messages,
+  OnEventHubTrigger,
+  OnEventHubTriggerConfig,
+  RawMessage,
+  RawMessages,
+} from 'event-hub-handler';
+export {
+  PLATFORM_CONTEXT_MANAGER,
+  PLATFORM_CONTEXT_PROVIDER,
+  PlatformContext,
+  PlatformContextManager,
+  PlatformContextProvider,
+  PlatformContextValueKey,
+  createPlatformContextValueKey,
+} from './context';
+export {
+  AUTHENTICATION_SERVICE,
+  AuthCtx,
+  AuthenticationService,
+  BadRequestError,
+  Body,
+  ControllerConfig,
+  ControllerOperationConfig,
+  ControllerRequestBodyOperationConfig,
+  Delete,
+  DirectResponseObject,
+  Get,
+  Head,
+  HeaderParam,
+  HeaderParamConfig,
+  HttpController,
+  HttpDirectResponseBuilder,
+  InternalServerError,
+  NotFoundError,
+  NumberSchema,
+  OptionalStringSchema,
+  Patch,
+  PathParam,
+  PathParamConfig,
+  Post,
+  Put,
+  QueryParam,
+  QueryParamConfig,
+  Request,
+  RestApplication,
+  StringSchema,
+  UnauthorizedError,
+} from './http-controller';
+export {
+  DEFAULT_LOG_LEVEL,
+  LOGGER_FACTORY,
+  LOGGER_NAME_PROVIDER,
+  LOG_LEVEL_PROVIDER,
+  LogLevel,
+  LogLevelProvider,
+  Logger,
+  LoggerFactory,
+  LoggerNameProvider,
+  OtelConfiguration,
+  SYSTEM_LOGGER_NAME_PREFIX,
+  TrieSearchService,
+} from './logger';
+export { startPlatform } from './middleware';
+export { IStartupService, STARTUP_SERVICE } from './platform';
+export { AUTHENTICATION_CONTEXT_KEY, AuthContext, AuthenticationError, Principal, SecurityContext } from './security';
+export {
+  AzFunctionsErrorOptions,
+  AzFunctionsRuntimeError,
+  InvocationCtx,
+  TriggerHandlerClass,
+  serviceIdentifier,
+} from './shared';

package/src/init.ts

@@ -0,0 +1,4 @@
+import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
+import { z } from 'zod';
+
+extendZodWithOpenApi(z);