transit-kit 0.3.1 → 0.4.0

package/dist/cli/generateOpenApi.js

@@ -31,6 +31,24 @@ function extractQueryParameters(querySchema) {
         return [];
     }
 }
+function extractRequestSecuritySchemes(definition) {
+    const securitySchemes = definition.securitySchemes;
+    if (hasValue(securitySchemes)) {
+        return securitySchemes.map((schema) => {
+            switch (schema.type) {
+                case "http":
+                    return {
+                        [schema.name]: [],
+                    };
+                default:
+                    throw new Error(`Unsupported security scheme type: ${schema.type}`);
+            }
+        });
+    }
+    else {
+        return [];
+    }
+}
 function translateToOpenAPIPathItem(definition) {
     const { meta, path, method, requestBodySchema, querySchema, responseSchemas, } = definition;
     // 1. Path and Parameter extraction
@@ -80,6 +98,8 @@ function translateToOpenAPIPathItem(definition) {
         .reduce((acc, resp) => {
         return { ...acc, ...resp };
     }, {});
+    // 5. Security Requirements
+    const securityRequirements = extractRequestSecuritySchemes(definition);
     const operation = {
         operationId: meta.name,
         summary: meta.description,
@@ -88,12 +108,35 @@ function translateToOpenAPIPathItem(definition) {
         parameters: operationParameters,
         ...requestBody,
         responses,
+        security: securityRequirements,
     };
     const pathItem = {
         [method.toLowerCase()]: operation,
     };
     return [openApiPath, pathItem];
 }
+function extractSecuritySchemes(endpointDefinitions) {
+    const securitySchemes = Array.from(new Set(endpointDefinitions
+        .map((def) => def.securitySchemes)
+        .filter(hasValue)
+        .flat()));
+    const openApiSecuritySchemes = securitySchemes.map((scheme) => {
+        switch (scheme.type) {
+            case "http":
+                return {
+                    [scheme.name]: {
+                        type: "http",
+                        scheme: scheme.scheme,
+                    },
+                };
+            default:
+                throw new Error(`Unsupported security scheme type: ${scheme.type}`);
+        }
+    });
+    return openApiSecuritySchemes.reduce((acc, scheme) => {
+        return { ...acc, ...scheme };
+    }, {});
+}
 export async function generateOpenApiDoc(targetPath) {
     const serverModule = await import(path.resolve(process.cwd(), targetPath));
     const server = serverModule.default;
@@ -114,6 +157,7 @@ export async function generateOpenApiDoc(targetPath) {
             }
             return acc;
         }, {});
+        const securitySchemes = extractSecuritySchemes(endpointDefinitions);
         const openApiDocument = {
             openapi: "3.0.0",
             info: {
@@ -121,6 +165,9 @@ export async function generateOpenApiDoc(targetPath) {
                 version: "1.0.0",
             },
             paths: paths,
+            components: {
+                securitySchemes,
+            },
         };
         return openApiDocument;
     }

package/dist/cli/generateOpenApi.spec.js

@@ -47,6 +47,7 @@ describe("translateToOpenAPIPathItem", () => {
                         schema: { type: "string" },
                     },
                 ],
+                security: [],
                 responses: {
                     "200": {
                         description: "Response for status code 200",

package/dist/server/handlers/api/EndpointDefinition.d.ts

@@ -1,16 +1,18 @@
 import z from "zod";
 import { HttpMethod } from "../../constants/HttpMethods";
+import { SecurityScheme } from "../../security/SecuritySchema";
 import { GenericResponseSchemaMap } from "./responses/index";
 export interface ApiEndpointMeta {
     name: string;
     group: string;
     description: string;
 }
-export type ApiEndpointDefinition<Path extends string = string, Method extends HttpMethod = HttpMethod, RequestBody extends z.ZodType | undefined = z.ZodType | undefined, Query extends z.ZodType | undefined = z.ZodType | undefined, ResponseMap extends GenericResponseSchemaMap = GenericResponseSchemaMap> = {
+export type ApiEndpointDefinition<Path extends string = string, Method extends HttpMethod = HttpMethod, RequestBody extends z.ZodType | undefined = z.ZodType | undefined, Query extends z.ZodType | undefined = z.ZodType | undefined, ResponseMap extends GenericResponseSchemaMap = GenericResponseSchemaMap, SecuritySchemes extends SecurityScheme<unknown>[] = SecurityScheme<unknown>[]> = {
     meta: ApiEndpointMeta;
     path: Path;
     method: Method;
     requestBodySchema?: RequestBody;
     querySchema?: Query;
     responseSchemas: ResponseMap;
+    securitySchemes?: SecuritySchemes;
 };

package/dist/server/handlers/api/EndpointHandler.d.ts

@@ -1,6 +1,11 @@
 import { Request } from "express";
 import { HttpStatusCodes } from "../../constants/HttpStatusCodes";
 import { GenericResponse } from "./responses";
-export type ApiEndpointHandler<PathParams extends Record<string, string> = {}, RequestBody = unknown, Query = unknown, Responses extends GenericResponse = never> = (request: Request<PathParams, unknown, RequestBody, Query, Record<string, unknown>>) => Promise<Responses | {
+export type ApiEndpointHandler<PathParams extends Record<string, string> = {}, RequestBody = unknown, Query = unknown, Responses extends GenericResponse = never, Caller = unknown> = (request: Request<PathParams, unknown, RequestBody, Query, Record<string, unknown>>, extractedRequestData: {
+    parameters: PathParams;
+    query: Query;
+    body: RequestBody;
+    caller: Caller;
+}) => Promise<Responses | {
     code: (typeof HttpStatusCodes)["InternalServerError_500"];
 }>;

package/dist/server/handlers/api/HandlerFromDefinition.d.ts

@@ -1,11 +1,12 @@
 import z from "zod";
 import { HttpStatusCode } from "../../constants/HttpStatusCodes";
+import { SecurityScheme } from "../../security/SecuritySchema";
 import { Prettify } from "../../utils/types";
 import { ApiEndpointHandler } from "./EndpointHandler";
 import { ExtractPathParams } from "./PathParameters";
 import { EmptyResponse, EmptyResponseSchema } from "./responses/emptyResponse";
 import { GenericResponse, GenericResponseSchemaMap } from "./responses/index";
 import { JsonResponseSchema, JsonResponseSchemaToResponseType } from "./responses/jsonResponse";
-export type HandlerForDefinition<Path extends string, RequestBody extends z.ZodType | undefined, Query extends z.ZodType | undefined, ResponsesMap extends GenericResponseSchemaMap> = ApiEndpointHandler<ExtractPathParams<Path>, RequestBody extends undefined ? undefined : z.infer<RequestBody>, Query extends undefined ? undefined : z.infer<Query>, Exclude<Prettify<{
+export type HandlerForDefinition<Path extends string, RequestBody extends z.ZodType | undefined, Query extends z.ZodType | undefined, ResponsesMap extends GenericResponseSchemaMap, SecuritySchemas extends SecurityScheme<unknown>[] = []> = ApiEndpointHandler<ExtractPathParams<Path>, RequestBody extends undefined ? undefined : z.infer<RequestBody>, Query extends undefined ? undefined : z.infer<Query>, Exclude<Prettify<{
     [K in keyof ResponsesMap]: K extends HttpStatusCode ? ResponsesMap[K] extends JsonResponseSchema ? JsonResponseSchemaToResponseType<K, ResponsesMap[K]> : ResponsesMap[K] extends EmptyResponseSchema ? EmptyResponse<K> : ResponsesMap[K] extends undefined ? never : GenericResponse : never;
-}[keyof ResponsesMap]>, undefined>>;
+}[keyof ResponsesMap]>, undefined>, SecuritySchemas extends SecurityScheme<infer Caller>[] ? Caller : unknown>;

package/dist/server/handlers/api/createApiHandler.d.ts

@@ -1,11 +1,12 @@
 import z from "zod";
 import { HttpMethod } from "../../constants/HttpMethods";
+import { SecurityScheme } from "../../security/SecuritySchema";
 import { Prettify } from "../../utils/types";
 import { ApiEndpointDefinition } from "./EndpointDefinition";
 import { ApiEndpointHandler } from "./EndpointHandler";
 import { HandlerForDefinition } from "./HandlerFromDefinition";
 import { GenericResponse, GenericResponseSchemaMap } from "./responses";
-export declare function createApiEndpointHandler<const ResponsesMap extends GenericResponseSchemaMap, const Path extends string, const Method extends HttpMethod, const RequestBody extends z.ZodType | undefined = undefined, const Query extends z.ZodType | undefined = undefined>(definition: Prettify<ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponsesMap>>, handler: HandlerForDefinition<Path, RequestBody, Query, ResponsesMap>): {
+export declare function createApiEndpointHandler<const ResponsesMap extends GenericResponseSchemaMap, const Path extends string, const Method extends HttpMethod, const RequestBody extends z.ZodType | undefined = undefined, const Query extends z.ZodType | undefined = undefined, const SecuritySchemas extends SecurityScheme<unknown>[] = []>(definition: Prettify<ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponsesMap, SecuritySchemas>>, handler: HandlerForDefinition<Path, RequestBody, Query, ResponsesMap>): {
     definition: {
         meta: import("./EndpointDefinition").ApiEndpointMeta;
         path: Path;
@@ -13,6 +14,7 @@ export declare function createApiEndpointHandler<const ResponsesMap extends Gene
         requestBodySchema?: RequestBody | undefined;
         querySchema?: Query | undefined;
         responseSchemas: ResponsesMap;
+        securitySchemes?: SecuritySchemas | undefined;
     };
     handler: HandlerForDefinition<Path, RequestBody, Query, ResponsesMap>;
 };

package/dist/server/handlers/api/createApiHandler.js

@@ -8,7 +8,14 @@ export function createApiEndpointHandler(definition, handler) {
 }
 export function buildApiEndpointHandler(handler) {
     return expressAsyncHandler(async (request, response) => {
-        const result = await handler(request);
+        const caller = response.locals.caller;
+        const extractedRequestData = {
+            parameters: request.params,
+            query: request.query,
+            body: request.body,
+            caller,
+        };
+        const result = await handler(request, extractedRequestData);
         if (isJsonResponse(result)) {
             response.status(result.code).json(result.json);
         }

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
 export { createApiEndpointHandler } from "./handlers/api/createApiHandler";
+export { buildAuthenticationMiddleware } from "./middleware/auth";
 export { createServer, type Server, type ServerConfig } from "./server";
 declare const _default: {};
 export default _default;

package/dist/server/index.js

@@ -1,3 +1,4 @@
 export { createApiEndpointHandler } from "./handlers/api/createApiHandler";
+export { buildAuthenticationMiddleware } from "./middleware/auth";
 export { createServer } from "./server";
 export default {};

package/dist/server/middleware/auth.d.ts

@@ -0,0 +1,2 @@
+import { SecurityScheme } from "../security/SecuritySchema";
+export declare function buildAuthenticationMiddleware<Caller>(schemes: SecurityScheme<Caller>[]): import("express").RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;

package/dist/server/middleware/auth.js

@@ -0,0 +1,13 @@
+import expressAsyncHandler from "express-async-handler";
+import { authenticate } from "../security/SecuritySchema";
+export function buildAuthenticationMiddleware(schemes) {
+    return expressAsyncHandler(async (request, response, next) => {
+        const caller = await authenticate(schemes, request);
+        if (caller == null) {
+            response.status(401).json({ message: "Unauthorized" });
+            return;
+        }
+        response.locals.caller = caller;
+        next();
+    });
+}

package/dist/server/security/SecuritySchema.d.ts

@@ -0,0 +1,5 @@
+import { Request } from "express";
+import { BasicAuthScheme } from "./basicAuth";
+import { BearerAuthScheme } from "./bearerAuth";
+export type SecurityScheme<Caller> = BasicAuthScheme<Caller> | BearerAuthScheme<Caller>;
+export declare function authenticate<Caller>(schemes: SecurityScheme<Caller>[], request: Request): Promise<Caller | null>;

package/dist/server/security/SecuritySchema.js

@@ -0,0 +1,14 @@
+import { buildBasicAuthenticator } from "./basicAuth";
+import { buildBearerAuthenticator } from "./bearerAuth";
+export async function authenticate(schemes, request) {
+    const authenticationResults = await Promise.all(schemes.map((scheme) => {
+        switch (scheme.scheme) {
+            case "basic":
+                return buildBasicAuthenticator(scheme)(request);
+            case "bearer":
+                return buildBearerAuthenticator(scheme)(request);
+        }
+    }));
+    const successfulAuthentication = authenticationResults.find((result) => result !== null);
+    return successfulAuthentication ?? null;
+}

package/dist/server/security/basicAuth.d.ts

@@ -0,0 +1,9 @@
+import { Request } from "express";
+export interface BasicAuthScheme<Caller = unknown> {
+    name: string;
+    type: "http";
+    scheme: "basic";
+    validateCaller: (username: string, password: string) => Promise<Caller | null>;
+}
+export declare function createBasicAuthSchema<Caller>(name: string, validateCaller: (username: string, password: string) => Promise<Caller | null>): BasicAuthScheme<Caller>;
+export declare function buildBasicAuthenticator<Caller>(scheme: BasicAuthScheme<Caller>): (request: Request) => Promise<Caller | null>;

package/dist/server/security/basicAuth.js

@@ -0,0 +1,21 @@
+import { hasNoValue } from "../utils/typeGuards";
+export function createBasicAuthSchema(name, validateCaller) {
+    return {
+        name,
+        type: "http",
+        scheme: "basic",
+        validateCaller,
+    };
+}
+export function buildBasicAuthenticator(scheme) {
+    return async (request) => {
+        const authHeader = request.headers.authorization;
+        if (hasNoValue(authHeader) || !authHeader.startsWith("Basic ")) {
+            return null;
+        }
+        const base64Credentials = authHeader.slice("Basic ".length);
+        const credentials = Buffer.from(base64Credentials, "base64").toString("utf-8");
+        const [username, password] = credentials.split(":", 2);
+        return scheme.validateCaller(username, password);
+    };
+}

package/dist/server/security/bearerAuth.d.ts

@@ -0,0 +1,9 @@
+import { Request } from "express";
+export interface BearerAuthScheme<Caller = unknown> {
+    name: string;
+    type: "http";
+    scheme: "bearer";
+    validateCaller: (token: string) => Promise<Caller | null>;
+}
+export declare function createBearerAuthSchema<Caller>(name: string, validateCaller: (token: string) => Promise<Caller | null>): BearerAuthScheme<Caller>;
+export declare function buildBearerAuthenticator<Caller>(scheme: BearerAuthScheme<Caller>): (request: Request) => Promise<Caller | null>;

package/dist/server/security/bearerAuth.js

@@ -0,0 +1,18 @@
+export function createBearerAuthSchema(name, validateCaller) {
+    return {
+        name,
+        type: "http",
+        scheme: "bearer",
+        validateCaller,
+    };
+}
+export function buildBearerAuthenticator(scheme) {
+    return async (request) => {
+        const authHeader = request.headers.authorization;
+        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
+            return null;
+        }
+        const token = authHeader.slice("Bearer ".length);
+        return scheme.validateCaller(token);
+    };
+}

package/dist/server/server.js

@@ -1,13 +1,18 @@
 import cookieParser from "cookie-parser";
 import express from "express";
 import { buildApiEndpointHandler } from "./handlers/api/createApiHandler";
+import { buildAuthenticationMiddleware } from "./middleware/auth";
 import { buildRequestLogger, buildResponseLogger } from "./middleware/logging";
 import { buildBodyValidatorMiddleware, buildQueryValidatorMiddleware, } from "./middleware/validation";
+import { isEmpty } from "./utils/funcs";
 import { NoOpLogger } from "./utils/logging";
 import { hasNoValue, hasValue } from "./utils/typeGuards";
 function registerApiEndpoint(expressApp, endpoint) {
     const { definition, handler } = endpoint;
     const handlerStack = [
+        hasValue(definition.securitySchemes) && !isEmpty(definition.securitySchemes)
+            ? buildAuthenticationMiddleware(definition.securitySchemes)
+            : null,
         hasValue(definition.querySchema)
             ? buildQueryValidatorMiddleware(definition.querySchema)
             : null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transit-kit",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A declarative TypeScript framework for building type-safe Express.js APIs with automatic OpenAPI generation",
   "keywords": [
     "express",