@twasik4/pocket-service 1.0.0 → 1.0.2

package/src/workers/auth/strategies.ts

@@ -0,0 +1,304 @@
+import { Request } from "express";
+import { createRemoteJWKSet, JWTPayload, jwtVerify } from "jose";
+import { PeerCertificate, TLSSocket } from "tls";
+import {
+  AuthenticatedUser,
+  AuthStrategy,
+  RouteDefinition,
+} from "../express-types";
+
+type JwtClaimValue = string | string[] | number | boolean | null | undefined;
+
+export type JwtStrategyClaims = {
+  sub?: string;
+  [key: string]: unknown;
+};
+
+export type JwtTokenVerifier = (
+  token: string,
+  req: Request,
+  route: RouteDefinition<any, any, boolean>,
+) => JwtStrategyClaims | null | Promise<JwtStrategyClaims | null>;
+
+export type CreateJwtAuthStrategyOptions = {
+  name?: string;
+  headerName?: string;
+  tokenPrefix?: string;
+  verifyToken: JwtTokenVerifier;
+  mapPayloadToUser?: (
+    claims: JwtStrategyClaims,
+    req: Request,
+    route: RouteDefinition<any, any, boolean>,
+  ) => AuthenticatedUser | null | Promise<AuthenticatedUser | null>;
+  canHandle?: AuthStrategy["canHandle"];
+};
+
+export type CreateJoseJwtVerifierOptions = {
+  jwksUri?: string;
+  secret?: string | Uint8Array;
+  issuer?: string | string[];
+  audience?: string | string[];
+  algorithms?: string[];
+  clockTolerance?: string | number;
+  requiredClaims?: string[];
+};
+
+export type CreateMtlsAuthStrategyOptions = {
+  name?: string;
+  requireAuthorized?: boolean;
+  mapCertificateToUser?: (
+    certificate: PeerCertificate,
+    req: Request,
+    route: RouteDefinition<any, any, boolean>,
+  ) => AuthenticatedUser | null | Promise<AuthenticatedUser | null>;
+  canHandle?: AuthStrategy["canHandle"];
+};
+
+function readAuthTokenFromHeader(
+  req: Request,
+  headerName: string,
+  tokenPrefix: string,
+): string | null {
+  const header = req.headers[headerName.toLowerCase()];
+
+  if (typeof header !== "string") {
+    return null;
+  }
+
+  const value = header.trim();
+  if (!value) {
+    return null;
+  }
+
+  if (!tokenPrefix) {
+    return value;
+  }
+
+  const prefix = `${tokenPrefix} `;
+  if (!value.startsWith(prefix)) {
+    return null;
+  }
+
+  return value.slice(prefix.length).trim() || null;
+}
+
+function isUserValue(
+  value: unknown,
+): value is Exclude<JwtClaimValue, null | undefined> {
+  return (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    (Array.isArray(value) && value.every((v) => typeof v === "string"))
+  );
+}
+
+function claimsToAuthenticatedUser(
+  claims: JwtStrategyClaims,
+): AuthenticatedUser | null {
+  if (typeof claims.sub !== "string" || claims.sub.length === 0) {
+    return null;
+  }
+
+  const user: AuthenticatedUser = { userId: claims.sub };
+  for (const [key, value] of Object.entries(claims)) {
+    if (key === "sub") {
+      continue;
+    }
+
+    if (isUserValue(value)) {
+      user[key] = value;
+    }
+  }
+
+  return user;
+}
+
+function jwtPayloadToStrategyClaims(payload: JWTPayload): JwtStrategyClaims {
+  const claims: JwtStrategyClaims = {};
+
+  for (const [key, value] of Object.entries(payload)) {
+    claims[key] = value;
+  }
+
+  if (typeof payload.sub === "string") {
+    claims.sub = payload.sub;
+  }
+
+  return claims;
+}
+
+function hasRequiredClaims(payload: JWTPayload, requiredClaims: string[]) {
+  return requiredClaims.every((claim) => payload[claim] !== undefined);
+}
+
+export function createJoseJwtVerifier(
+  options: CreateJoseJwtVerifierOptions,
+): JwtTokenVerifier {
+  const requiredClaims = options.requiredClaims ?? ["sub"];
+  const jwtVerifyOptions = {
+    issuer: options.issuer,
+    audience: options.audience,
+    algorithms: options.algorithms,
+    clockTolerance: options.clockTolerance,
+  };
+
+  if (options.jwksUri) {
+    const jwksKeySource = createRemoteJWKSet(new URL(options.jwksUri));
+
+    return async (token) => {
+      try {
+        const { payload } = await jwtVerify(
+          token,
+          jwksKeySource,
+          jwtVerifyOptions,
+        );
+
+        if (!hasRequiredClaims(payload, requiredClaims)) {
+          return null;
+        }
+
+        return jwtPayloadToStrategyClaims(payload);
+      } catch {
+        return null;
+      }
+    };
+  }
+
+  const secretKey =
+    typeof options.secret === "string"
+      ? new TextEncoder().encode(options.secret)
+      : options.secret;
+
+  if (!(secretKey instanceof Uint8Array)) {
+    throw new Error("createJoseJwtVerifier requires either jwksUri or secret.");
+  }
+
+  return async (token) => {
+    try {
+      const { payload } = await jwtVerify(token, secretKey, jwtVerifyOptions);
+
+      if (!hasRequiredClaims(payload, requiredClaims)) {
+        return null;
+      }
+
+      return jwtPayloadToStrategyClaims(payload);
+    } catch {
+      return null;
+    }
+  };
+}
+
+function parseSubjectAltNames(subjectAltName?: string): string[] {
+  if (!subjectAltName) {
+    return [];
+  }
+
+  return subjectAltName
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function resolveMtlsIdentity(certificate: PeerCertificate): string | null {
+  const sans = parseSubjectAltNames(certificate.subjectaltname);
+  const uriSan = sans.find((value) => value.startsWith("URI:"));
+  if (uriSan) {
+    return uriSan.slice(4).trim() || null;
+  }
+
+  const dnsSan = sans.find((value) => value.startsWith("DNS:"));
+  if (dnsSan) {
+    return dnsSan.slice(4).trim() || null;
+  }
+
+  const subjectCn = certificate.subject?.CN;
+  if (typeof subjectCn === "string" && subjectCn.length > 0) {
+    return subjectCn;
+  }
+  if (Array.isArray(subjectCn) && subjectCn.length > 0) {
+    const first = subjectCn[0];
+    if (typeof first === "string" && first.length > 0) {
+      return first;
+    }
+  }
+
+  if (certificate.fingerprint256) {
+    return certificate.fingerprint256;
+  }
+
+  return null;
+}
+
+export function createJwtAuthStrategy(
+  options: CreateJwtAuthStrategyOptions,
+): AuthStrategy {
+  const headerName = options.headerName ?? "authorization";
+  const tokenPrefix = options.tokenPrefix ?? "Bearer";
+
+  return {
+    name: options.name ?? "jwt",
+    canHandle: options.canHandle,
+    authenticate: async (req, route) => {
+      const token = readAuthTokenFromHeader(req, headerName, tokenPrefix);
+      if (!token) {
+        return null;
+      }
+
+      const claims = await options.verifyToken(token, req, route);
+      if (!claims) {
+        return null;
+      }
+
+      if (options.mapPayloadToUser) {
+        return options.mapPayloadToUser(claims, req, route);
+      }
+
+      return claimsToAuthenticatedUser(claims);
+    },
+  };
+}
+
+export function createMtlsAuthStrategy(
+  options: CreateMtlsAuthStrategyOptions = {},
+): AuthStrategy {
+  const requireAuthorized = options.requireAuthorized ?? true;
+
+  return {
+    name: options.name ?? "mtls",
+    canHandle: options.canHandle,
+    authenticate: async (req, route) => {
+      const socket = req.socket as TLSSocket;
+      if (typeof socket.getPeerCertificate !== "function") {
+        return null;
+      }
+
+      if (requireAuthorized && socket.authorized !== true) {
+        return null;
+      }
+
+      const certificate = socket.getPeerCertificate(true);
+      if (!certificate || Object.keys(certificate).length === 0) {
+        return null;
+      }
+
+      if (options.mapCertificateToUser) {
+        return options.mapCertificateToUser(certificate, req, route);
+      }
+
+      const userId = resolveMtlsIdentity(certificate);
+      if (!userId) {
+        return null;
+      }
+
+      return {
+        userId,
+        certSubjectCn: certificate.subject?.CN ?? "",
+        certIssuerCn: certificate.issuer?.CN ?? "",
+        certFingerprint256: certificate.fingerprint256 ?? "",
+        certSerialNumber: certificate.serialNumber ?? "",
+        mtlsAuthorized: socket.authorized,
+      };
+    },
+  };
+}

package/src/workers/express-types.ts

@@ -22,6 +22,74 @@ export type AuthenticatedUser = {
   [key: string]: string | string[] | number | boolean;
 };
 
+export type AuthResolver = (
+  req: Request,
+  route: RouteDefinition<any, any, boolean>,
+) => AuthenticatedUser | null | Promise<AuthenticatedUser | null>;
+
+export type AuthStrategy = {
+  name: string;
+  canHandle?: (
+    req: Request,
+    route: RouteDefinition<any, any, boolean>,
+  ) => boolean | Promise<boolean>;
+  authenticate: AuthResolver;
+};
+
+export function defaultHeaderAuthResolver(
+  req: Request,
+): AuthenticatedUser | null {
+  const userIdHeader = req.headers["x-user-id"];
+  const userMetaHeader = req.headers["x-user-meta"];
+
+  if (typeof userMetaHeader === "string") {
+    try {
+      const parsed = JSON.parse(userMetaHeader) as Partial<AuthenticatedUser>;
+
+      if (typeof parsed.userId === "string") {
+        return parsed as AuthenticatedUser;
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  if (typeof userIdHeader !== "string") {
+    return null;
+  }
+
+  return {
+    userId: userIdHeader,
+  };
+}
+
+export function createAuthResolver(
+  strategies: AuthStrategy[],
+  opts: { fallbackResolver?: AuthResolver } = {},
+): AuthResolver {
+  return async (req, route) => {
+    for (const strategy of strategies) {
+      if (strategy.canHandle) {
+        const canHandle = await strategy.canHandle(req, route);
+        if (!canHandle) {
+          continue;
+        }
+      }
+
+      const user = await strategy.authenticate(req, route);
+      if (user) {
+        return user;
+      }
+    }
+
+    if (opts.fallbackResolver) {
+      return opts.fallbackResolver(req, route);
+    }
+
+    return null;
+  };
+}
+
 export type TypedRequest<
   TBody = unknown,
   TParams = unknown,
@@ -76,6 +144,12 @@ export function getRegisteredRoutes() {
   return registeredRoutes;
 }
 
+type CreateMetaRouterOptions = {
+  authResolver?: AuthResolver;
+  onUnauthorized?: (req: Request, res: Response) => void;
+  onAuthError?: (err: unknown, req: Request, res: Response) => void;
+};
+
 /**
  * Utility function to create an Express router with enhanced type safety and built-in support for request validation and authentication. This function allows you to define routes with associated Zod schemas for validating request bodies and URL parameters, as well as specifying whether authentication is required for each route. The returned object includes the configured Express router, a list of registered routes for introspection, and a helper function to add new routes with the specified configurations.
  */
@@ -135,34 +209,87 @@ export function createMetaRouter(): {
       TRequireAuth
     >,
   ) => void;
+} {
+  return createMetaRouterWithAuth();
+}
+
+export function createMetaRouterWithAuth(options?: CreateMetaRouterOptions): {
+  /**
+   * The Express router instance that can be used to register routes and middleware. This router is configured to work with the enhanced route definitions provided by the `addRoute` function, which supports request validation and authentication requirements.
+   */
+  router: Router;
+  /**
+   * List of registered routes with their configurations, which can be used for introspection, documentation generation, or analytics purposes. Each entry includes the HTTP method, full path, authentication requirement, validation schemas, and any additional metadata provided during route registration.
+   */
+  routes: RouteDefinition<any, any, boolean>[];
+  /**
+   * Adds a new route to the router with the specified configuration and request handler.
+   *
+   * - If `requireAuth` is set to true, the route will automatically include middleware to check for an authenticated user and return a 401 error if the user is not authenticated.
+   * - If `bodyValidator` or `paramsValidator` are provided, the route will include middleware to validate the request body and URL parameters against the provided Zod schemas, returning a 400 error if validation fails.
+   *
+   * The route definition is also stored in an internal list for introspection purposes.
+   *
+   * @param route The route definition, including method, path, validation schemas, and authentication requirements.
+   * @param handler The request handler function for the route.
+   * @returns void
+   *
+   * @example
+   * addRoute(
+   *   {
+   *     fullPath: "/me",
+   *     method: "GET",
+   *     requireAuth: true,
+   *     meta: {
+   *       description: "Get current authenticated user info",
+   *     },
+   *   },
+   *   async (req, res) => {
+   *     try {
+   *       ...fetch user info from database using req.user.userId...
+   *       res.status(200).json(...user info...);
+   *     } catch (err) {
+   *       console.error("Failed to fetch user info:", err);
+   *       res
+   *         .status(500)
+   *         .json({ isSuccess: false, message: "Internal server error" });
+   *     }
+   *   },
+   * );
+   */
+  addRoute: <
+    TBody extends ZodSchema | undefined = undefined,
+    TParams extends ZodSchema | undefined = undefined,
+    TRequireAuth extends boolean = false,
+  >(
+    route: RouteDefinition<TBody, TParams, TRequireAuth>,
+    /** Request handler for the route */ handler: TypedRequestHandler<
+      TBody,
+      TParams,
+      TRequireAuth
+    >,
+  ) => void;
 } {
   const router = Router();
   const routes: RouteDefinition<any, any, boolean>[] = [];
-
-  function readAuthenticatedUser(req: Request): AuthenticatedUser | null {
-    const userIdHeader = req.headers["x-user-id"];
-    const userMetaHeader = req.headers["x-user-meta"];
-
-    if (typeof userMetaHeader === "string") {
-      try {
-        const parsed = JSON.parse(userMetaHeader) as Partial<AuthenticatedUser>;
-
-        if (typeof parsed.userId === "string") {
-          return parsed as AuthenticatedUser;
-        }
-      } catch {
-        return null;
-      }
-    }
-
-    if (typeof userIdHeader !== "string") {
-      return null;
-    }
-
-    return {
-      userId: userIdHeader,
-    };
-  }
+  const authResolver: AuthResolver =
+    options?.authResolver ?? ((req) => defaultHeaderAuthResolver(req));
+  const onUnauthorized =
+    options?.onUnauthorized ??
+    ((_: Request, res: Response) => {
+      res.status(401).json({
+        isSuccess: false,
+        message: "Unauthorized",
+      });
+    });
+  const onAuthError =
+    options?.onAuthError ??
+    ((_: unknown, __: Request, res: Response) => {
+      res.status(401).json({
+        isSuccess: false,
+        message: "Unauthorized",
+      });
+    });
 
   /**
    * Adds a new route to the router with the specified configuration and request handler.
@@ -222,19 +349,20 @@ export function createMetaRouter(): {
       paramsValidator,
     });
     if (route.requireAuth) {
-      middlewareStack.push((req, res, next) => {
-        const user = readAuthenticatedUser(req);
+      middlewareStack.push(async (req, res, next) => {
+        try {
+          const user = await authResolver(req, route);
 
-        if (!user) {
-          res.status(401).json({
-            isSuccess: false,
-            message: "Unauthorized",
-          });
-          return;
-        }
+          if (!user) {
+            onUnauthorized(req, res);
+            return;
+          }
 
-        (req as TypedRequest<TBody, TParams, true>).user = user;
-        next();
+          (req as TypedRequest<TBody, TParams, true>).user = user;
+          next();
+        } catch (err) {
+          onAuthError(err, req, res);
+        }
       });
     }
     if (bodyValidator && route.method !== "GET") {

package/src/workers/index.ts

@@ -2,5 +2,6 @@ export * from "./service";
 export * from "./stream-handler";
 export * from "./types";
 export * from "./express-types";
+export * from "./auth/strategies";
 export * from "./db/mongo/mongo";
 export * from "./db/mongo/collection";

package/src/workers/service.ts

@@ -4,7 +4,15 @@ import path from "path";
 import { createClient, RedisClientType } from "redis";
 import { Logger } from "winston";
 import { Worker } from "worker_threads";
-import { createMetaRouter, RouteDefinition } from "./express-types";
+import {
+  AuthResolver,
+  AuthStrategy,
+  createAuthResolver,
+  createMetaRouter,
+  createMetaRouterWithAuth,
+  defaultHeaderAuthResolver,
+  RouteDefinition,
+} from "./express-types";
 import { ClickhouseConfig, createTypedClickhouse } from "./db/clickhouse";
 import {
   createMongo,
@@ -39,12 +47,27 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
   private serviceStreamSubscriptions: string[] = [];
   private _status: "starting" | "running" | "stopped" | "stopping" = "starting";
   private readonly HEARTBEAT_INTERVAL = 1000 * 5;
+  private authStrategies: AuthStrategy[] = [];
+  private authResolverOverride?: AuthResolver;
+  private useDefaultHeaderAuthFallback = true;
   private expressOptions: ExpressOptions = {
     corsWhitelist: ["*"],
     asJson: true,
     customMiddleware: [],
   };
 
+  private getAuthResolver(): AuthResolver {
+    if (this.authResolverOverride) {
+      return this.authResolverOverride;
+    }
+
+    return createAuthResolver(this.authStrategies, {
+      fallbackResolver: this.useDefaultHeaderAuthFallback
+        ? (req) => defaultHeaderAuthResolver(req)
+        : undefined,
+    });
+  }
+
   get streamKey() {
     return this.simpleName + ":events";
   }
@@ -428,7 +451,9 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
 
   private initBaseRoutes() {
     this.log.info("Registering base routes");
-    const { router, routes, addRoute } = createMetaRouter();
+    const { router, routes, addRoute } = createMetaRouterWithAuth({
+      authResolver: this.getAuthResolver(),
+    });
 
     addRoute(
       {
@@ -487,7 +512,9 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
    * Default worker routes under /workers
    */
   private initWorkerRoutes(): void {
-    const { router, routes, addRoute } = createMetaRouter();
+    const { router, routes, addRoute } = createMetaRouterWithAuth({
+      authResolver: this.getAuthResolver(),
+    });
 
     addRoute(
       {
@@ -830,6 +857,26 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
     return this;
   }
 
+  withAuthStrategy(strategy: AuthStrategy) {
+    this.authStrategies.push(strategy);
+    return this;
+  }
+
+  withAuthStrategies(strategies: AuthStrategy[]) {
+    this.authStrategies.push(...strategies);
+    return this;
+  }
+
+  withAuthResolver(resolver: AuthResolver) {
+    this.authResolverOverride = resolver;
+    return this;
+  }
+
+  withoutDefaultHeaderAuthFallback() {
+    this.useDefaultHeaderAuthFallback = false;
+    return this;
+  }
+
   private internalAddRouter(
     base: string,
     router: Router,