@conduitplatform/module-tools 0.17.0-alpha.7 → 0.17.0-alpha.9

package/dist/index.esm.js

@@ -402,9 +402,9 @@ var GrpcServer = class {
 import path2 from "path";
 import { EventEmitter } from "events";
 import { camelCase } from "lodash-es";
-import { status as status3 } from "@grpc/grpc-js";
+import { status as status5 } from "@grpc/grpc-js";
 import {
-  ConduitGrpcSdk as ConduitGrpcSdk4,
+  ConduitGrpcSdk as ConduitGrpcSdk6,
   HealthCheckResponse_ServingStatus,
   HealthCheckStatus
 } from "@conduitplatform/grpc-sdk";
@@ -487,6 +487,16 @@ var RouteBuilder = class {
     this._options.captureRawHeaders = capture;
     return this;
   }
+  /**
+   * Whether module-tools hydrates `context.user` from `context.userId` on routes with
+   * `authMiddleware` / `authMiddleware?` (default true).
+   * @deprecated The default flips to false in the next major; call
+   * `grpcSdk.authentication.getUser(userId)` explicitly instead.
+   */
+  hydrateUser(hydrate) {
+    this._options.hydrateUser = hydrate;
+    return this;
+  }
   return(name, fields) {
     this._returns = new ConduitRouteReturnDefinition(name, fields);
     return this;
@@ -520,45 +530,105 @@ var RouteBuilder = class {
 
 // src/routing/wrapRouterFunctions.ts
 import {
-  ConduitGrpcSdk as ConduitGrpcSdk3
+  ConduitGrpcSdk as ConduitGrpcSdk4
 } from "@conduitplatform/grpc-sdk";
+import { status as status3 } from "@grpc/grpc-js";
+
+// src/routing/hydrateUser.ts
+import { ConduitGrpcSdk as ConduitGrpcSdk3, GrpcError as GrpcError2 } from "@conduitplatform/grpc-sdk";
 import { status as status2 } from "@grpc/grpc-js";
+function middlewareList(routeOptions) {
+  const m = routeOptions?.middlewares;
+  if (Array.isArray(m)) return m.filter((x) => typeof x === "string");
+  if (typeof m === "string") return [m];
+  return [];
+}
+function getAuthMiddlewareKind(routeOptions) {
+  const list = middlewareList(routeOptions);
+  if (list.includes("authMiddleware")) return "required";
+  if (list.includes("authMiddleware?")) return "optional";
+  return void 0;
+}
+function shouldHydrateUser(routeOptions, context) {
+  if (!routeOptions || !context) return false;
+  if (routeOptions.hydrateUser === false) return false;
+  if (!getAuthMiddlewareKind(routeOptions)) return false;
+  return typeof context.userId === "string" && !!context.userId && !context.user;
+}
+function createUserHydrator(routeOptions, resolve) {
+  if (!routeOptions) return void 0;
+  const kind = getAuthMiddlewareKind(routeOptions);
+  if (!kind || routeOptions.hydrateUser === false) return void 0;
+  return {
+    optional: kind === "optional",
+    getUser: async (userId) => {
+      const resolver = resolve();
+      if (!resolver) throw new GrpcError2(status2.UNAVAILABLE, "User lookup unavailable");
+      return resolver(userId);
+    }
+  };
+}
+function mapHydrationErrorCode(error) {
+  const code = error?.code;
+  if (typeof code !== "number" || code === status2.OK) return status2.INTERNAL;
+  if (code === status2.NOT_FOUND) return status2.UNAUTHENTICATED;
+  return code;
+}
+async function hydrateContextUser(routeOptions, context, hydrator) {
+  if (!shouldHydrateUser(routeOptions, context)) return;
+  try {
+    context.user = await hydrator.getUser(context.userId);
+  } catch (e) {
+    ConduitGrpcSdk3.Logger.warn(
+      `User hydration failed: ${e?.message ?? String(e)}`
+    );
+    if (!hydrator.optional) {
+      const code = mapHydrationErrorCode(e);
+      throw new GrpcError2(
+        code,
+        code === status2.UNAUTHENTICATED ? "Unauthorized" : "User lookup failed"
+      );
+    }
+  }
+}
+
+// src/routing/wrapRouterFunctions.ts
 var mapGrpcStatusToHttp = (code) => {
   if (!code) return "200 (OK)";
   switch (code) {
-    case status2.OK:
+    case status3.OK:
       return `200 (OK)`;
-    case status2.CANCELLED:
+    case status3.CANCELLED:
       return `499 (Cancelled)`;
-    case status2.INVALID_ARGUMENT:
+    case status3.INVALID_ARGUMENT:
       return `400 (Invalid Argument)`;
-    case status2.DEADLINE_EXCEEDED:
+    case status3.DEADLINE_EXCEEDED:
       return `504 (Deadline Exceeded)`;
-    case status2.NOT_FOUND:
+    case status3.NOT_FOUND:
       return `404 (Not Found)`;
-    case status2.ALREADY_EXISTS:
+    case status3.ALREADY_EXISTS:
       return `409 (Already Exists)`;
-    case status2.PERMISSION_DENIED:
+    case status3.PERMISSION_DENIED:
       return `403 (Permission Denied)`;
-    case status2.UNAUTHENTICATED:
+    case status3.UNAUTHENTICATED:
       return `401 (Unauthenticated)`;
-    case status2.OUT_OF_RANGE:
+    case status3.OUT_OF_RANGE:
       return `416 (Out of Range)`;
-    case status2.FAILED_PRECONDITION:
+    case status3.FAILED_PRECONDITION:
       return `412 (Failed Precondition)`;
-    case status2.ABORTED:
+    case status3.ABORTED:
       return `409 (Aborted)`;
-    case status2.INTERNAL:
+    case status3.INTERNAL:
       return `416 (Internal)`;
-    case status2.UNAVAILABLE:
+    case status3.UNAVAILABLE:
       return `503 (Service Unavailable)`;
-    case status2.DATA_LOSS:
+    case status3.DATA_LOSS:
       return `500 (Data Loss)`;
     default:
       return `500 (Unknown)`;
   }
 };
-function generateLog(routerType, routerRequest, requestReceive, call, status6) {
+function generateLog(routerType, routerRequest, requestReceive, call, status10) {
   let log = "";
   const latency = Date.now() - requestReceive;
   if (routerRequest) {
@@ -568,15 +638,15 @@ function generateLog(routerType, routerRequest, requestReceive, call, status6) {
     const socketLabel = socketReq.socketId ?? socketReq.socket;
     log += `(${routerType})  Socket: ${socketReq.event} socket: ${socketLabel}`;
   }
-  log += ` ${mapGrpcStatusToHttp(status6) ?? "200"} ${latency}ms`;
-  ConduitGrpcSdk3.Logger.log(log);
-  ConduitGrpcSdk3.Metrics?.set("grpc_request_latency_seconds", latency / 1e3);
-  ConduitGrpcSdk3.Metrics?.set(
+  log += ` ${mapGrpcStatusToHttp(status10) ?? "200"} ${latency}ms`;
+  ConduitGrpcSdk4.Logger.log(log);
+  ConduitGrpcSdk4.Metrics?.set("grpc_request_latency_seconds", latency / 1e3);
+  ConduitGrpcSdk4.Metrics?.set(
     `${routerType}_grpc_request_latency_seconds`,
     latency / 1e3
   );
-  const successStatus = !status6 || status6.toString().startsWith("2");
-  ConduitGrpcSdk3.Metrics?.increment(`${routerType}_grpc_response_statuses_total`, 1, {
+  const successStatus = !status10 || status10.toString().startsWith("2");
+  ConduitGrpcSdk4.Metrics?.increment(`${routerType}_grpc_response_statuses_total`, 1, {
     success: successStatus ? "true" : "false"
   });
 }
@@ -592,7 +662,7 @@ function parseResponseData(r, routerRequest, requestReceive, call, callback, res
   responded.did = true;
   if (!r) {
     callback({
-      code: status2.INTERNAL,
+      code: status3.INTERNAL,
       message: "Handler did not return a response"
     });
   }
@@ -623,11 +693,11 @@ function parseResponseData(r, routerRequest, requestReceive, call, callback, res
   }
   generateLog(routerType, routerRequest, requestReceive, call, void 0);
 }
-function wrapRouterGrpcFunction(fun, routerType) {
+function wrapRouterGrpcFunction(fun, routerType, hydration) {
   return (call, callback) => {
     const requestReceive = Date.now();
     let routerRequest = true;
-    ConduitGrpcSdk3.Metrics?.increment(`${routerType}_grpc_requests_total`);
+    ConduitGrpcSdk4.Metrics?.increment(`${routerType}_grpc_requests_total`);
     try {
       call.request.context = parseRequestData(call.request.context);
       call.request.params = parseRequestData(call.request.params);
@@ -646,16 +716,16 @@ function wrapRouterGrpcFunction(fun, routerType) {
         }
       }
     } catch (e) {
-      ConduitGrpcSdk3.Metrics?.increment(`${routerType}_grpc_errors_total`);
-      generateLog(routerType, routerRequest, requestReceive, call, status2.INTERNAL);
-      ConduitGrpcSdk3.Logger.error(e.message ?? "Something went wrong");
+      ConduitGrpcSdk4.Metrics?.increment(`${routerType}_grpc_errors_total`);
+      generateLog(routerType, routerRequest, requestReceive, call, status3.INTERNAL);
+      ConduitGrpcSdk4.Logger.error(e.message ?? "Something went wrong");
       return callback({
-        code: status2.INTERNAL,
+        code: status3.INTERNAL,
         message: e.message ?? "Something went wrong"
       });
     }
     const responded = { did: false };
-    fun(call, (r) => {
+    const invoke = () => fun(call, (r) => {
       parseResponseData(
         r,
         routerRequest,
@@ -665,7 +735,13 @@ function wrapRouterGrpcFunction(fun, routerType) {
         responded,
         routerType
       );
-    }).then(
+    });
+    const needsHydration = hydration && shouldHydrateUser(hydration.options, call.request.context);
+    (needsHydration ? hydrateContextUser(
+      hydration.options,
+      call.request.context,
+      hydration.hydrator
+    ).then(invoke) : invoke()).then(
       (r) => parseResponseData(
         r,
         routerRequest,
@@ -676,19 +752,19 @@ function wrapRouterGrpcFunction(fun, routerType) {
         routerType
       )
     ).catch((error) => {
-      ConduitGrpcSdk3.Metrics?.increment(`${routerType}_grpc_errors_total`);
+      ConduitGrpcSdk4.Metrics?.increment(`${routerType}_grpc_errors_total`);
       generateLog(
         routerType,
         routerRequest,
         requestReceive,
         call,
-        error.code ?? status2.INTERNAL
+        error.code ?? status3.INTERNAL
       );
-      ConduitGrpcSdk3.Logger.error(
+      ConduitGrpcSdk4.Logger.error(
         error.debugLogInfo ?? error.message ?? "Something went wrong"
       );
       callback({
-        code: error.code ?? status2.INTERNAL,
+        code: error.code ?? status3.INTERNAL,
         message: error.details ?? error.message ?? "Something went wrong"
       });
     });
@@ -696,10 +772,14 @@ function wrapRouterGrpcFunction(fun, routerType) {
 }
 
 // src/routing/RoutingUtilities.ts
-function wrapFunctionsAsync(functions, routerType) {
+function wrapFunctionsAsync(functions, routerType, hydrations = {}) {
   const modifiedFunctions = {};
   Object.keys(functions).forEach((key) => {
-    modifiedFunctions[key] = wrapRouterGrpcFunction(functions[key], routerType);
+    modifiedFunctions[key] = wrapRouterGrpcFunction(
+      functions[key],
+      routerType,
+      hydrations[key]
+    );
   });
   return modifiedFunctions;
 }
@@ -707,8 +787,11 @@ function wrapFunctionsAsync(functions, routerType) {
 // src/routing/RoutingManager.ts
 import {
   Admin,
-  ConduitRouteActions as ConduitRouteActions2
+  ConduitRouteActions as ConduitRouteActions2,
+  ConduitGrpcSdk as ConduitGrpcSdk5,
+  GrpcError as GrpcError3
 } from "@conduitplatform/grpc-sdk";
+import { status as status4 } from "@grpc/grpc-js";
 var RoutingManager = class _RoutingManager {
   constructor(_router, _server) {
     this._router = _router;
@@ -722,6 +805,30 @@ var RoutingManager = class _RoutingManager {
   _moduleRoutes = {};
   static ClientController;
   static AdminController;
+  /** Set by ManagedModule; used to hydrate context.user on client routes. */
+  static grpcSdk;
+  static userResolver;
+  static warnedNoResolver = false;
+  /**
+   * Overrides how users are fetched for hydration (default: grpcSdk.authentication.getUser).
+   * Intended for the module that owns the users: the authentication module has no gRPC
+   * client to itself and will register a local resolver here.
+   */
+  static setUserResolver(resolver) {
+    _RoutingManager.userResolver = resolver;
+  }
+  static resolveUser() {
+    if (_RoutingManager.userResolver) return _RoutingManager.userResolver;
+    const sdk = _RoutingManager.grpcSdk;
+    if (!sdk) return void 0;
+    return async (userId) => {
+      const auth = sdk.authentication;
+      if (!auth) {
+        throw new GrpcError3(status4.UNAVAILABLE, "authentication module unavailable");
+      }
+      return auth.getUser(userId);
+    };
+  }
   _routeHandlers = {};
   isAdmin = false;
   get(path5) {
@@ -788,7 +895,27 @@ var RoutingManager = class _RoutingManager {
   }
   async registerRoutes() {
     if (Object.keys(this._routeHandlers).length === 0) return;
-    const modifiedFunctions = wrapFunctionsAsync(this._routeHandlers, this.isAdmin ? "admin" : "client");
+    const hydrations = {};
+    if (!this.isAdmin) {
+      for (const [name, route] of Object.entries(this._moduleRoutes)) {
+        const options = route.options;
+        const hydrator = createUserHydrator(options, _RoutingManager.resolveUser);
+        if (!hydrator) continue;
+        const names = "events" in route ? Object.keys(JSON.parse(route.events || "{}")) : [name];
+        for (const n of names) hydrations[n] = { options, hydrator };
+        if (!_RoutingManager.grpcSdk && !_RoutingManager.userResolver && !_RoutingManager.warnedNoResolver) {
+          _RoutingManager.warnedNoResolver = true;
+          ConduitGrpcSdk5.Logger.warn(
+            "User hydration is needed but RoutingManager.grpcSdk is not set; hydration will fail"
+          );
+        }
+      }
+    }
+    const modifiedFunctions = wrapFunctionsAsync(
+      this._routeHandlers,
+      this.isAdmin ? "admin" : "client",
+      hydrations
+    );
     if (this.isAdmin) {
       _RoutingManager.AdminController.setRoutes(modifiedFunctions);
     } else {
@@ -867,7 +994,7 @@ var ConduitServiceModule = class {
       );
     }
     if (!init) {
-      ConduitGrpcSdk4.Metrics?.set(
+      ConduitGrpcSdk6.Metrics?.set(
         "module_health_state",
         state === HealthCheckStatus.SERVING ? 1 : 0
       );
@@ -910,9 +1037,9 @@ var ConduitServiceModule = class {
     } else {
       this.events.on(
         `grpc-health-change:${this._serviceName}`,
-        (status6) => {
+        (status10) => {
           call.write({
-            status: status6
+            status: status10
           });
         }
       );
@@ -935,7 +1062,7 @@ var ConduitServiceModule = class {
       const resources = this.getExportableResources();
       callback(null, { resources: JSON.stringify(resources) });
     } catch (e) {
-      callback({ code: status3.INTERNAL, message: e.message });
+      callback({ code: status5.INTERNAL, message: e.message });
     }
   }
   async exportResourcesHandler(call, callback) {
@@ -944,7 +1071,7 @@ var ConduitServiceModule = class {
       const data = await this.exportResources(resourceTypes);
       callback(null, { data: JSON.stringify(data) });
     } catch (e) {
-      callback({ code: status3.INTERNAL, message: e.message });
+      callback({ code: status5.INTERNAL, message: e.message });
     }
   }
   async importResourcesHandler(call, callback) {
@@ -956,11 +1083,11 @@ var ConduitServiceModule = class {
       const err = e;
       if (err instanceof SyntaxError) {
         callback({
-          code: status3.INVALID_ARGUMENT,
+          code: status5.INVALID_ARGUMENT,
           message: "Invalid JSON in import data"
         });
       } else {
-        callback({ code: status3.INTERNAL, message: err.message });
+        callback({ code: status5.INTERNAL, message: err.message });
       }
     }
   }
@@ -1033,7 +1160,7 @@ var ConfigController = class _ConfigController {
 
 // src/ManagedModule.ts
 import { kebabCase } from "lodash-es";
-import { status as status5 } from "@grpc/grpc-js";
+import { status as status9 } from "@grpc/grpc-js";
 import convict from "convict";
 
 // src/interfaces/ModuleLifecycleStage.ts
@@ -1048,18 +1175,18 @@ var ModuleLifecycleStage = /* @__PURE__ */ ((ModuleLifecycleStage2) => {
 
 // src/ManagedModule.ts
 import {
-  ConduitGrpcSdk as ConduitGrpcSdk8
+  ConduitGrpcSdk as ConduitGrpcSdk11
 } from "@conduitplatform/grpc-sdk";
 
 // src/utilities/initializeSdk.ts
 import {
-  ConduitGrpcSdk as ConduitGrpcSdk7,
+  ConduitGrpcSdk as ConduitGrpcSdk9,
   HealthCheckStatus as HealthCheckStatus2
 } from "@conduitplatform/grpc-sdk";
 
 // src/logging/index.ts
 import {
-  ConduitGrpcSdk as ConduitGrpcSdk5
+  ConduitGrpcSdk as ConduitGrpcSdk7
 } from "@conduitplatform/grpc-sdk";
 import winston, { format } from "winston";
 import { isEmpty } from "lodash-es";
@@ -1217,7 +1344,7 @@ async function setupLoki(module, instance) {
     if (lokiUrl.endsWith("/")) lokiUrl = lokiUrl.slice(0, -1);
     const onTry = async () => {
       return await lokiReadyCheck(lokiUrl).then(() => {
-        ConduitGrpcSdk5.Logger.addTransport(
+        ConduitGrpcSdk7.Logger.addTransport(
           new LokiTransport({
             level: "debug",
             host: lokiUrl,
@@ -1236,15 +1363,90 @@ async function setupLoki(module, instance) {
       }).catch(() => true);
     };
     const onFailure = () => {
-      ConduitGrpcSdk5.Logger.error(`Failed to connect to Loki on '${lokiUrl}'`);
+      ConduitGrpcSdk7.Logger.error(`Failed to connect to Loki on '${lokiUrl}'`);
     };
     await linearBackoffTimeoutAsync(onTry, 250, 15, onFailure, true);
   }
 }
 
-// src/utilities/initializeSdk.ts
-import winston2 from "winston";
+// src/logging/fileTransports.ts
+import fs from "fs";
+import os from "os";
 import path3 from "path";
+import winston2 from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+var DEFAULT_RETENTION_DAYS = 3;
+var DEFAULT_MAX_SIZE = "20m";
+var SIZE_STRING = /^(?:0\.)?\d+[kmg]$/i;
+function positiveIntFromEnv(raw, fallback) {
+  if (raw === void 0) return fallback;
+  const trimmed = raw.trim();
+  if (!/^[0-9]+$/.test(trimmed)) return fallback;
+  const value = Number(trimmed);
+  if (!Number.isSafeInteger(value) || value <= 0) return fallback;
+  return value;
+}
+function logFileMaxSize() {
+  const raw = process.env.LOG_FILE_MAX_SIZE?.trim();
+  if (!raw) return DEFAULT_MAX_SIZE;
+  if (SIZE_STRING.test(raw)) return raw.toLowerCase();
+  if (/^[0-9]+$/.test(raw)) {
+    const bytes = Number(raw);
+    if (Number.isSafeInteger(bytes) && bytes > 0) return bytes;
+  }
+  return DEFAULT_MAX_SIZE;
+}
+function formatMeta(meta) {
+  if (Array.isArray(meta)) {
+    if (meta.length === 0) return "";
+    return meta.map((item) => JSON.stringify(item)).join(" ");
+  }
+  if (meta !== null && typeof meta === "object") {
+    if (Object.keys(meta).length === 0) return "";
+    return JSON.stringify(meta);
+  }
+  return "";
+}
+function createFileFormat() {
+  return winston2.format.combine(
+    winston2.format.errors({ stack: true }),
+    winston2.format.timestamp({
+      format: "YYYY-MM-DD HH:mm:ss"
+    }),
+    winston2.format.printf((info) => {
+      const metaText = formatMeta(info.meta);
+      const line = `[${info.timestamp}] [${info.level.toUpperCase()}]: ${info.message}`;
+      if (info.stack) {
+        return `${line} ${info.stack}`;
+      }
+      return metaText ? `${line} ${metaText}` : line;
+    })
+  );
+}
+function rotateTransport(logDir, name, level) {
+  return new DailyRotateFile({
+    dirname: logDir,
+    filename: `${name}-%DATE%.log`,
+    datePattern: "YYYY-MM-DD",
+    level,
+    maxFiles: `${positiveIntFromEnv(process.env.LOG_RETENTION_DAYS, DEFAULT_RETENTION_DAYS)}d`,
+    maxSize: logFileMaxSize(),
+    zippedArchive: false,
+    auditFile: path3.join(logDir, `.${name}-audit.json`),
+    format: createFileFormat()
+  });
+}
+function createFileLogTransports() {
+  if (process.env.LOG_TO_FILE?.trim() === "false") {
+    return [];
+  }
+  const logDir = process.env.LOG_FILE_DIR?.trim() || path3.join(os.tmpdir(), "conduit-logs");
+  fs.mkdirSync(logDir, { recursive: true });
+  return [
+    rotateTransport(logDir, "combined", "info"),
+    rotateTransport(logDir, "errors", "error")
+  ];
+}
 
 // src/metrics/index.ts
 import {
@@ -1259,7 +1461,7 @@ import {
 // src/metrics/MetricsServer.ts
 import { createServer as createServer2 } from "http";
 import { isNaN } from "lodash-es";
-import { ConduitGrpcSdk as ConduitGrpcSdk6 } from "@conduitplatform/grpc-sdk";
+import { ConduitGrpcSdk as ConduitGrpcSdk8 } from "@conduitplatform/grpc-sdk";
 var MetricsServer = class {
   moduleName;
   instance;
@@ -1274,7 +1476,7 @@ var MetricsServer = class {
     const url = "0.0.0.0:" + port.toString();
     const server = createServer2(this.requestHandler.bind(this));
     server.listen(port, () => {
-      ConduitGrpcSdk6.Logger.info(`Metrics server listening on: ${url}`);
+      ConduitGrpcSdk8.Logger.info(`Metrics server listening on: ${url}`);
     });
     return server;
   }
@@ -1296,12 +1498,12 @@ var MetricsServer = class {
   getHttpPort() {
     const value = process.env["METRICS_PORT"];
     if (!value) {
-      ConduitGrpcSdk6.Logger.error(`Metrics HTTP port not set`);
+      ConduitGrpcSdk8.Logger.error(`Metrics HTTP port not set`);
       process.exit(-1);
     }
     const port = parseInt(value, 10);
     if (isNaN(port) || port < 1 || port > 65535) {
-      ConduitGrpcSdk6.Logger.error(`Invalid HTTP port value: ${port}`);
+      ConduitGrpcSdk8.Logger.error(`Invalid HTTP port value: ${port}`);
       process.exit(-1);
     }
     return port;
@@ -1593,7 +1795,7 @@ function clientMiddleware() {
     clientStartedMetric.inc(labels);
     const stopTimer = clientHandlingSecondsMetric.startTimer(labels);
     let settled = false;
-    let status6 = Status.OK;
+    let status10 = Status.OK;
     try {
       let request;
       if (!call.requestStream) {
@@ -1619,21 +1821,21 @@ function clientMiddleware() {
     } catch (err) {
       settled = true;
       if (err instanceof ClientError) {
-        status6 = err.code;
+        status10 = err.code;
       } else if (isAbortError(err)) {
-        status6 = Status.ABORTED;
+        status10 = Status.ABORTED;
       } else {
-        status6 = Status.UNKNOWN;
+        status10 = Status.UNKNOWN;
       }
       throw err;
     } finally {
       if (!settled) {
-        status6 = Status.CANCELLED;
+        status10 = Status.CANCELLED;
       }
-      stopTimer({ [codeLabel]: Status[status6] });
+      stopTimer({ [codeLabel]: Status[status10] });
       clientHandledMetric.inc({
         ...labels,
-        [codeLabel]: Status[status6]
+        [codeLabel]: Status[status10]
       });
     }
   };
@@ -1643,20 +1845,12 @@ function clientMiddleware() {
 var initializeSdk = (coreUrl, moduleName, watchModules = true, serviceHealthStatusGetter = () => HealthCheckStatus2.SERVING) => {
   let logger;
   try {
-    logger = new ConduitLogger([
-      new winston2.transports.File({
-        filename: path3.join(__dirname, ".logs/combined.log"),
-        level: "info"
-      }),
-      new winston2.transports.File({
-        filename: path3.join(__dirname, ".logs/errors.log"),
-        level: "error"
-      })
-    ]);
-  } catch (e) {
+    const fileTransports = createFileLogTransports();
+    logger = fileTransports.length > 0 ? new ConduitLogger(fileTransports) : new ConduitLogger();
+  } catch {
     logger = new ConduitLogger();
   }
-  const grpcSdk = new ConduitGrpcSdk7(
+  const grpcSdk = new ConduitGrpcSdk9(
     coreUrl,
     moduleName,
     watchModules,
@@ -1665,7 +1859,7 @@ var initializeSdk = (coreUrl, moduleName, watchModules = true, serviceHealthStat
   );
   setupLoki(grpcSdk.name, grpcSdk.instance).then();
   if (process.env.METRICS_PORT) {
-    ConduitGrpcSdk7.Metrics = new ConduitMetrics(grpcSdk.name, grpcSdk.instance);
+    ConduitGrpcSdk9.Metrics = new ConduitMetrics(grpcSdk.name, grpcSdk.instance);
     grpcSdk.addMiddleware(clientMiddleware());
   }
   return grpcSdk;
@@ -1863,8 +2057,346 @@ async function reconcileStoredModuleConfig(args) {
   return { config: persisted, persisted: true };
 }
 
+// src/utilities/accessTokenVerifier.ts
+import { ConduitGrpcSdk as ConduitGrpcSdk10, GrpcError as GrpcError5 } from "@conduitplatform/grpc-sdk";
+import { status as status7 } from "@grpc/grpc-js";
+import { createPublicKey } from "crypto";
+
+// src/utilities/accessTokenVerifier.logic.ts
+import { createDecoder, createVerifier as createVerifier2 } from "fast-jwt";
+import { status as status6 } from "@grpc/grpc-js";
+import { GrpcError as GrpcError4 } from "@conduitplatform/grpc-sdk";
+var DEFAULT_LEEWAY_SECONDS = 5;
+var verifiers = /* @__PURE__ */ new Map();
+var decode = createDecoder({ complete: true });
+function fail(reason) {
+  throw new GrpcError4(status6.UNAUTHENTICATED, reason);
+}
+function getVerifier(publicKey) {
+  let verifier = verifiers.get(publicKey);
+  if (!verifier) {
+    verifier = createVerifier2({
+      key: publicKey,
+      algorithms: ["EdDSA"],
+      ignoreExpiration: true,
+      ignoreNotBefore: true,
+      cache: false
+    });
+    verifiers.set(publicKey, verifier);
+  }
+  return verifier;
+}
+function selectVerificationKey(kid, signing, now) {
+  if (!kid) return void 0;
+  if (signing.publicKey && kid === signing.kid) return signing.publicKey;
+  if (signing.previousKid && signing.previousPublicKey && kid === signing.previousKid && (signing.previousRetiredAt ?? 0) > now) {
+    return signing.previousPublicKey;
+  }
+  return void 0;
+}
+function verifyAccessToken(token, state, options = {}) {
+  const now = options.now ?? Date.now();
+  const leeway = options.leewaySeconds ?? DEFAULT_LEEWAY_SECONDS;
+  if (typeof token !== "string" || token.length === 0) fail("malformed token");
+  let kid;
+  try {
+    const decoded = decode(token);
+    if (decoded.header.alg !== "EdDSA") fail("unsupported algorithm");
+    kid = decoded.header.kid;
+  } catch (e) {
+    if (e instanceof GrpcError4) throw e;
+    fail("malformed token");
+  }
+  const key = selectVerificationKey(kid, state.signing, now);
+  if (!key) fail("unknown kid");
+  let claims;
+  try {
+    claims = getVerifier(key)(token);
+  } catch {
+    fail("bad signature");
+  }
+  if (typeof claims.sub !== "string" || typeof claims.sid !== "string" || typeof claims.exp !== "number") {
+    fail("malformed token");
+  }
+  if (now / 1e3 >= claims.exp + leeway) fail("expired");
+  if (claims.tv !== state.tokenVersion) fail("version mismatch");
+  if (options.clientId !== void 0 && claims.cid !== options.clientId) {
+    fail("client mismatch");
+  }
+  return claims;
+}
+
+// src/utilities/accessTokenVerifier.ts
+var AUTHENTICATION_CONFIG_UPDATE_CHANNEL = "authentication:config:update";
+var INITIAL_RETRY_MS = 1e3;
+var MAX_RETRY_MS = 3e4;
+var REFRESH_INTERVAL_MS = 5 * 60 * 1e3;
+var UNKNOWN_KID_REFETCH_MIN_MS = 10 * 1e3;
+var SUBSCRIBER_ID = "access-token-verifier";
+function isConfigWithAccessTokens(config) {
+  return typeof config === "object" && config !== null && typeof config.accessTokens === "object" && config.accessTokens !== null;
+}
+var AccessTokenVerifier = class _AccessTokenVerifier {
+  constructor(grpcSdk) {
+    this.grpcSdk = grpcSdk;
+  }
+  grpcSdk;
+  static instance;
+  _mode = "session";
+  _strictRevocation = false;
+  _tokenVersion = 0;
+  _signing;
+  _loaded = false;
+  _subscribed = false;
+  _generation = 0;
+  _running = false;
+  _retryTimer;
+  _refreshTimer;
+  _lastRefetch = 0;
+  _refetching = false;
+  _warned = /* @__PURE__ */ new Set();
+  _listeners = /* @__PURE__ */ new Set();
+  static getInstance(grpcSdk) {
+    if (!_AccessTokenVerifier.instance) {
+      _AccessTokenVerifier.instance = new _AccessTokenVerifier(grpcSdk);
+    }
+    return _AccessTokenVerifier.instance;
+  }
+  /**
+   * Internal, for tests only: stops the verifier, clears all state and drops the singleton.
+   */
+  static resetForTests() {
+    _AccessTokenVerifier.instance?.stop();
+    _AccessTokenVerifier.instance?.resetState();
+    _AccessTokenVerifier.instance = void 0;
+  }
+  resetState() {
+    this._mode = "session";
+    this._strictRevocation = false;
+    this._tokenVersion = 0;
+    this._signing = void 0;
+    this._loaded = false;
+    this._lastRefetch = 0;
+    this._warned.clear();
+    this._listeners.clear();
+  }
+  /** Snapshot of the verifier's observable state. */
+  get state() {
+    return {
+      mode: this._mode,
+      strictRevocation: this._strictRevocation,
+      ready: this.ready,
+      tokenVersion: this._tokenVersion,
+      kid: this._signing?.kid
+    };
+  }
+  /**
+   * Registers a listener fired synchronously at the end of every applyConfig that changed
+   * anything (including the first successful load). Returns an unsubscribe function.
+   */
+  onChange(listener) {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+  fingerprint() {
+    return JSON.stringify([this._loaded, this._signing, this.state]);
+  }
+  get mode() {
+    return this._mode;
+  }
+  get strictRevocation() {
+    return this._strictRevocation;
+  }
+  /** True once signing keys have been loaded. */
+  get ready() {
+    return !!this._signing?.publicKey;
+  }
+  get tokenVersion() {
+    return this._tokenVersion;
+  }
+  /**
+   * Loads the authentication config, subscribes to its updates and starts a slow periodic
+   * refresh. The first attempt is awaited; if it fails, retries continue in the background
+   * with capped backoff until the config is loaded and the subscription is acknowledged.
+   * Idempotent while running; never throws.
+   */
+  async start() {
+    if (this._running) return;
+    this._running = true;
+    const generation = ++this._generation;
+    await this.attempt(generation, INITIAL_RETRY_MS);
+    if (generation !== this._generation) return;
+    this._refreshTimer = setInterval(() => void this.refetch(true), REFRESH_INTERVAL_MS);
+    this._refreshTimer.unref?.();
+  }
+  stop() {
+    this._running = false;
+    this._generation++;
+    if (this._retryTimer) clearTimeout(this._retryTimer);
+    if (this._refreshTimer) clearInterval(this._refreshTimer);
+    this._retryTimer = void 0;
+    this._refreshTimer = void 0;
+    if (this._subscribed) {
+      try {
+        this.grpcSdk.bus?.unsubscribe(SUBSCRIBER_ID);
+      } catch {
+      }
+      this._subscribed = false;
+    }
+  }
+  async attempt(generation, delay) {
+    if (generation !== this._generation) return;
+    try {
+      await this.subscribe(generation);
+      if (!this._loaded) {
+        this.applyConfig(await this.grpcSdk.config.get("authentication"));
+      }
+    } catch {
+    }
+    if (generation !== this._generation) return;
+    if (this._subscribed && this._loaded) return;
+    this._retryTimer = setTimeout(
+      () => void this.attempt(generation, Math.min(delay * 2, MAX_RETRY_MS)),
+      delay
+    );
+    this._retryTimer.unref?.();
+  }
+  async subscribe(generation) {
+    if (this._subscribed) return;
+    const bus = this.grpcSdk.bus;
+    if (!bus) return;
+    await bus.subscribeAck(
+      AUTHENTICATION_CONFIG_UPDATE_CHANNEL,
+      (message) => {
+        try {
+          this.applyConfig(JSON.parse(message));
+        } catch {
+        }
+      },
+      SUBSCRIBER_ID
+    );
+    if (generation !== this._generation) {
+      bus.unsubscribe(SUBSCRIBER_ID);
+      return;
+    }
+    this._subscribed = true;
+  }
+  /** Refetches the config from the authentication module; failures keep the previous state. */
+  async refetch(force = false) {
+    const now = Date.now();
+    if (this._refetching) return;
+    if (!force && now - this._lastRefetch < UNKNOWN_KID_REFETCH_MIN_MS) return;
+    this._lastRefetch = now;
+    this._refetching = true;
+    try {
+      this.applyConfig(await this.grpcSdk.config.get("authentication"));
+    } catch {
+    } finally {
+      this._refetching = false;
+    }
+  }
+  warnOnce(key, message) {
+    if (this._warned.has(key)) return;
+    this._warned.add(key);
+    ConduitGrpcSdk10.Logger.warn(`AccessTokenVerifier: ${message}`);
+  }
+  static validPem(pem) {
+    if (typeof pem !== "string" || !pem) return false;
+    try {
+      createPublicKey(pem);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Validates and normalizes the signing keys. Returns undefined when no signing block is
+   * configured, null when the public key is invalid (the caller keeps the previous state).
+   */
+  normalizeSigning(s) {
+    if (!(s && typeof s.kid === "string" && s.kid && s.publicKey)) return void 0;
+    if (!_AccessTokenVerifier.validPem(s.publicKey)) {
+      this.warnOnce("publicKey", "invalid signing public key, keeping previous state");
+      return null;
+    }
+    const previousPublicKey = this.validPreviousKey(s.previousPublicKey);
+    return {
+      kid: s.kid,
+      publicKey: s.publicKey,
+      previousKid: previousPublicKey ? s.previousKid || void 0 : void 0,
+      previousPublicKey,
+      previousRetiredAt: Number(s.previousRetiredAt ?? 0)
+    };
+  }
+  validPreviousKey(pem) {
+    if (!pem) return void 0;
+    if (_AccessTokenVerifier.validPem(pem)) return pem;
+    this.warnOnce("previousPublicKey", "invalid previous public key, ignoring it");
+    return void 0;
+  }
+  parseTokenVersion(raw) {
+    const version = Number(raw ?? 0);
+    if (Number.isNaN(version)) {
+      this.warnOnce("tokenVersion", "invalid tokenVersion, all tokens will be rejected");
+    }
+    return version;
+  }
+  notifyListeners() {
+    const state = this.state;
+    for (const listener of [...this._listeners]) {
+      try {
+        listener(state);
+      } catch (e) {
+        ConduitGrpcSdk10.Logger.warn(
+          `AccessTokenVerifier: change listener failed: ${e?.message}`
+        );
+      }
+    }
+  }
+  /**
+   * Applies an authentication module config object (full config). Invalid input is ignored
+   * and the previous state is kept; invalid keys are logged once.
+   */
+  applyConfig(config) {
+    if (!isConfigWithAccessTokens(config)) return;
+    const tokens = config.accessTokens;
+    const before = this.fingerprint();
+    const signing = this.normalizeSigning(tokens.signing);
+    if (signing === null) return;
+    const version = this.parseTokenVersion(tokens.tokenVersion);
+    this._mode = tokens.mode === "jwt" ? "jwt" : "session";
+    this._tokenVersion = version;
+    this._strictRevocation = tokens.strictRevocation === true;
+    this._signing = signing;
+    this._loaded = true;
+    if (this.fingerprint() !== before) this.notifyListeners();
+  }
+  /**
+   * Verifies an access token, throwing GrpcError(UNAUTHENTICATED) with a short reason on failure.
+   * `options.now` is epoch milliseconds. An `unknown kid` triggers a throttled (at most once
+   * per 10 s) background refetch of the config, to pick up a rotation sooner.
+   */
+  verify(token, options) {
+    if (!this._signing) {
+      throw new GrpcError5(status7.UNAUTHENTICATED, "verifier not ready");
+    }
+    try {
+      return verifyAccessToken(
+        token,
+        { tokenVersion: this._tokenVersion, signing: this._signing },
+        options
+      );
+    } catch (e) {
+      if (e.message === "unknown kid") void this.refetch();
+      throw e;
+    }
+  }
+};
+
 // src/routing/RoutingController.ts
-import { status as status4 } from "@grpc/grpc-js";
+import { status as status8 } from "@grpc/grpc-js";
 var RoutingController = class {
   _routeHandlers = {};
   handleRequest(call, callback) {
@@ -1872,7 +2404,7 @@ var RoutingController = class {
       this._routeHandlers[call.request.functionName](call, callback);
     } else {
       callback({
-        code: status4.NOT_FOUND,
+        code: status8.NOT_FOUND,
         message: "Not found"
       });
     }
@@ -1931,13 +2463,13 @@ var ManagedModule = class extends ConduitServiceModule {
       await this.preRegisterLifecycle();
       await this.grpcSdk.config.registerModule(this.name, this.address, this.healthState);
     } catch (err) {
-      ConduitGrpcSdk8.Logger.error("Failed to initialize server");
-      ConduitGrpcSdk8.Logger.error(err);
+      ConduitGrpcSdk11.Logger.error("Failed to initialize server");
+      ConduitGrpcSdk11.Logger.error(err);
       process.exit(-1);
     }
     await this.postRegisterLifecycle().catch((err) => {
-      ConduitGrpcSdk8.Logger.error("Failed to activate module");
-      ConduitGrpcSdk8.Logger.error(err);
+      ConduitGrpcSdk11.Logger.error("Failed to activate module");
+      ConduitGrpcSdk11.Logger.error(err);
       process.exit(-1);
     });
   }
@@ -2004,11 +2536,11 @@ var ManagedModule = class extends ConduitServiceModule {
    * Registers common and module-specific metric types.
    */
   async registerMetrics() {
-    if (ConduitGrpcSdk8.Metrics) {
-      ConduitGrpcSdk8.Metrics.initializeDefaultMetrics();
+    if (ConduitGrpcSdk11.Metrics) {
+      ConduitGrpcSdk11.Metrics.initializeDefaultMetrics();
       if (this.metricsSchema) {
         Object.values(this.metricsSchema).forEach((metric) => {
-          ConduitGrpcSdk8.Metrics.registerMetric(metric.type, metric.config);
+          ConduitGrpcSdk11.Metrics.registerMetric(metric.type, metric.config);
         });
       }
     }
@@ -2032,7 +2564,7 @@ var ManagedModule = class extends ConduitServiceModule {
     const known = new Set(this.grpcSdk.getKnownModuleNames());
     for (const n of names) {
       if (!known.has(n)) {
-        ConduitGrpcSdk8.Logger.warn(
+        ConduitGrpcSdk11.Logger.warn(
           `Declared Conduit peer "${n}" is not a known built-in module (see ConduitGrpcSdk.getKnownModuleNames).`
         );
       }
@@ -2093,18 +2625,19 @@ var ManagedModule = class extends ConduitServiceModule {
         this.service.functions
       );
     }
+    RoutingManager.grpcSdk = this.grpcSdk;
     RoutingManager.ClientController = new RoutingController();
     RoutingManager.AdminController = new RoutingController();
     await this.addHealthCheckService();
     await this.addModuleService();
     await this.grpcServer.start();
-    ConduitGrpcSdk8.Logger.log("gRPC server listening on " + this._port);
+    ConduitGrpcSdk11.Logger.log("gRPC server listening on " + this._port);
   }
   async setConfig(call, callback) {
     try {
       if (!this.config) {
         return callback({
-          code: status5.INVALID_ARGUMENT,
+          code: status9.INVALID_ARGUMENT,
           message: "Module is not configurable"
         });
       }
@@ -2123,7 +2656,7 @@ var ManagedModule = class extends ConduitServiceModule {
         this.config = convict(this.configSchema);
         this.config.load(previousConfig);
         return callback({
-          code: status5.INVALID_ARGUMENT,
+          code: status9.INVALID_ARGUMENT,
           message: "Invalid configuration values: " + e.message
         });
       }
@@ -2132,7 +2665,7 @@ var ManagedModule = class extends ConduitServiceModule {
       await this._drainConfigQueue();
       this.grpcSdk.bus?.publish(kebabCase(this.name) + ":config:update", configJson);
     } catch (e) {
-      return callback({ code: status5.INTERNAL, message: e.message });
+      return callback({ code: status9.INTERNAL, message: e.message });
     }
   }
   /** Used to update the module's configuration on initial Redis/DB reconciliation. */
@@ -2212,8 +2745,8 @@ var ManagedModule = class extends ConduitServiceModule {
 };
 
 // src/classes/ModuleError.ts
-import { GrpcError as GrpcError2 } from "@conduitplatform/grpc-sdk";
-var ModuleError = class extends GrpcError2 {
+import { GrpcError as GrpcError6 } from "@conduitplatform/grpc-sdk";
+var ModuleError = class extends GrpcError6 {
   debugLogInfo;
   constructor(errorDefinition, debugLogInfo) {
     const { grpcCode, conduitCode, message } = errorDefinition;
@@ -2228,6 +2761,8 @@ var ModuleError = class extends GrpcError2 {
   }
 };
 export {
+  AUTHENTICATION_CONFIG_UPDATE_CHANNEL,
+  AccessTokenVerifier,
   ConduitActiveSchema,
   ConduitBoolean,
   ConduitDate,
@@ -2238,6 +2773,7 @@ export {
   ConduitServiceModule,
   ConduitString,
   ConfigController,
+  DEFAULT_LEEWAY_SECONDS,
   DEFAULT_STRIP_FIELDS,
   GrpcServer,
   ManagedModule,
@@ -2250,20 +2786,27 @@ export {
   convictConfigParser,
   createParsedRouterRequest,
   createServer,
+  createUserHydrator,
   exportModel,
+  getAuthMiddlewareKind,
+  hydrateContextUser,
   importModel,
   initializeSdk,
   linearBackoffTimeout,
   linearBackoffTimeoutAsync,
+  mapHydrationErrorCode,
   merge,
   readConduitPeersManifest,
   reconcileStoredModuleConfig,
   redactSensitiveConfig,
   restoreRedactedSecrets,
   sanitizeDocumentsForExport,
+  selectVerificationKey,
+  shouldHydrateUser,
   stableConfigJson,
   storedConfigsEquivalent,
   stripInternalFields,
+  verifyAccessToken,
   wrapFunctionsAsync,
   wrapGrpcFunctions,
   wrapRouterGrpcFunction