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

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ConduitSchema, DatabaseProvider, ConduitModel, ConduitSchemaOptions, Query, FindOneOptions, FindManyOptions, AuthzOptions, PopulateAuthzOptions, CountDocumentsOptions, ConduitGrpcSdk, HealthCheckStatus, GrpcRequest, HealthCheckRequest, GrpcCallback, HealthCheckResponse, SetConfigRequest, GrpcResponse, SetConfigResponse, GetExportableResourcesRequest, GetExportableResourcesResponse, ExportResourcesRequest, ExportResourcesResponse, ImportResourcesRequest, ImportResourcesResponse, PeerWatchEdge, TYPE, ConduitNumberValidation, ConduitStringValidation, Params, Context, Cookies, ParsedRouterRequest, UnparsedRouterResponse, ConduitSocketParamTypes, ConduitRouteReturnDefinition, ParsedSocketRequest, UnparsedSocketResponse, Indexable, Router, Admin, ConduitMiddlewareOptions, ConduitRouteOptions, ConduitSocketOptions, ConduitRouteActions, ConduitQueryParams, ConduitUrlParams, ConduitReturn, ConduitRoute, GrpcError, ModuleErrorDefinition } from '@conduitplatform/grpc-sdk';
+import { ConduitSchema, DatabaseProvider, ConduitModel, ConduitSchemaOptions, Query, FindOneOptions, FindManyOptions, AuthzOptions, PopulateAuthzOptions, CountDocumentsOptions, ConduitGrpcSdk, HealthCheckStatus, GrpcRequest, HealthCheckRequest, GrpcCallback, HealthCheckResponse, SetConfigRequest, GrpcResponse, SetConfigResponse, GetExportableResourcesRequest, GetExportableResourcesResponse, ExportResourcesRequest, ExportResourcesResponse, ImportResourcesRequest, ImportResourcesResponse, PeerWatchEdge, TYPE, ConduitNumberValidation, ConduitStringValidation, Params, Context, Cookies, ParsedRouterRequest, Indexable, UnparsedRouterResponse, ConduitSocketParamTypes, ConduitRouteReturnDefinition, ParsedSocketRequest, UnparsedSocketResponse, Router, Admin, ConduitMiddlewareOptions, ConduitRouteOptions, ConduitSocketOptions, ConduitRouteActions, ConduitQueryParams, ConduitUrlParams, ConduitReturn, ConduitRoute, AccessTokenClaims, GrpcError, ModuleErrorDefinition } from '@conduitplatform/grpc-sdk';
 import { EventEmitter } from 'events';
 import { ServerWritableStream, Server } from '@grpc/grpc-js';
 import convict from 'convict';
@@ -345,6 +345,49 @@ declare function wrapGrpcFunctions(functions: {
 
 declare function createParsedRouterRequest(params: Params, urlParams?: Params, queryParams?: Params, bodyParams?: Params, path?: string, headers?: Headers, context?: Context, cookies?: Cookies, rawHeaders?: string[], rawBody?: Buffer): ParsedRouterRequest;
 
+/**
+ * User hydration.
+ *
+ * Client routes guarded by `authMiddleware` / `authMiddleware?` receive `context.user`.
+ * In "session" mode the authentication middleware already sets it. In "jwt" mode the
+ * router only knows the user id (`context.userId`, from a verified access token), so
+ * module-tools fetches the user (through grpcSdk.authentication.getUser, which reads
+ * through a 5s Redis cache) before invoking the handler.
+ *
+ * Opt out per route with `hydrateUser: false` (RouteBuilder.hydrateUser(false)).
+ *
+ * @deprecated The default flips to off in the next major version. Modules are then
+ * expected to call `grpcSdk.authentication.getUser(context.userId)` explicitly.
+ */
+interface UserHydrator {
+    /** True for `authMiddleware?`: a failed lookup leaves the context untouched. */
+    optional: boolean;
+    getUser: (userId: string) => Promise<Indexable>;
+}
+/** Whether the route is guarded by an auth middleware, and if so whether it is the optional form. */
+declare function getAuthMiddlewareKind(routeOptions: Indexable): 'required' | 'optional' | undefined;
+/**
+ * Pure hydration decision: the route has an auth middleware, `hydrateUser` is not false,
+ * and the context carries a `userId` but no `user`. Admin routes must not call this.
+ */
+declare function shouldHydrateUser(routeOptions: Indexable | undefined, context: Indexable | undefined): boolean;
+type UserResolver = (userId: string) => Promise<Indexable>;
+/**
+ * Builds the per-route hydrator for client routes, or undefined when the route never hydrates.
+ * `resolve` is consulted per request (so a resolver registered after route registration still
+ * applies) and returns the lookup function to use, if any.
+ */
+declare function createUserHydrator(routeOptions: Indexable | undefined, resolve: () => UserResolver | undefined): UserHydrator | undefined;
+/** Maps a failed user lookup to the gRPC code returned to the caller. */
+declare function mapHydrationErrorCode(error: unknown): number;
+/**
+ * Sets context.user when needed. For the mandatory form a failed lookup throws a GrpcError:
+ * NOT_FOUND becomes UNAUTHENTICATED; PERMISSION_DENIED and every other gRPC code
+ * (UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, ...) pass through. The optional form
+ * swallows the failure and leaves the context untouched. Failures are logged at warn level.
+ */
+declare function hydrateContextUser(routeOptions: Indexable, context: Indexable, hydrator: UserHydrator): Promise<void>;
+
 type RouterRequestHandler = (call: ParsedRouterRequest) => Promise<UnparsedRouterResponse>;
 type RouterRequestHandlerCallback = (call: ParsedRouterRequest, callback: (response: UnparsedRouterResponse) => void) => Promise<UnparsedRouterResponse | undefined | void>;
 type SocketRequestHandler = (call: ParsedSocketRequest) => Promise<UnparsedSocketResponse>;
@@ -356,7 +399,10 @@ interface SocketEventHandler {
     returnType?: ConduitRouteReturnDefinition;
     handler: SocketRequestHandlers;
 }
-declare function wrapRouterGrpcFunction(fun: RequestHandlers | SocketRequestHandlers, routerType: string): (call: Indexable, callback: any) => void;
+declare function wrapRouterGrpcFunction(fun: RequestHandlers | SocketRequestHandlers, routerType: string, hydration?: {
+    options: Indexable;
+    hydrator: UserHydrator;
+}): (call: Indexable, callback: any) => void;
 
 declare class RoutingController {
     private _routeHandlers;
@@ -372,6 +418,17 @@ declare class RoutingManager {
     private _moduleRoutes;
     static ClientController: RoutingController;
     static AdminController: RoutingController;
+    /** Set by ManagedModule; used to hydrate context.user on client routes. */
+    static grpcSdk?: ConduitGrpcSdk;
+    private static userResolver?;
+    private static warnedNoResolver;
+    /**
+     * 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: UserResolver | undefined): void;
+    private static resolveUser;
     private _routeHandlers;
     private readonly isAdmin;
     constructor(_router: Router | Admin, _server: GrpcServer);
@@ -409,6 +466,13 @@ declare class RouteBuilder {
     rateLimit(maxRequests: number, resetInterval: number): RouteBuilder;
     captureRawBody(capture: boolean): RouteBuilder;
     captureRawHeaders(capture: boolean): RouteBuilder;
+    /**
+     * 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: boolean): RouteBuilder;
     return(name: string, fields: ConduitReturn): RouteBuilder;
     handler(fn: RequestHandlers): RouteBuilder;
     add(): void;
@@ -417,7 +481,12 @@ declare class RouteBuilder {
 
 declare function wrapFunctionsAsync(functions: {
     [name: string]: RequestHandlers | SocketRequestHandlers;
-}, routerType: 'admin' | 'client'): {
+}, routerType: 'admin' | 'client', hydrations?: {
+    [name: string]: {
+        options: Indexable;
+        hydrator: UserHydrator;
+    };
+}): {
     [name: string]: (call: Indexable, callback?: Indexable) => void;
 };
 
@@ -502,9 +571,121 @@ declare function reconcileStoredModuleConfig<T>(args: {
     persisted: boolean;
 }>;
 
+interface AccessTokenSigningKeys {
+    kid: string;
+    /** PEM (SPKI) Ed25519 public key. */
+    publicKey: string;
+    previousKid?: string;
+    previousPublicKey?: string;
+    /** Epoch ms until which the previous key is still accepted. 0 (or unset) means no previous key. */
+    previousRetiredAt?: number;
+}
+interface AccessTokenVerifierState {
+    tokenVersion: number;
+    signing: AccessTokenSigningKeys;
+}
+interface AccessTokenVerifyOptions {
+    /** Client id of the request. When set, it must equal the token's `cid`. */
+    clientId?: string;
+    /** Current time in epoch milliseconds. Defaults to Date.now(). */
+    now?: number;
+    /** Clock skew tolerance for `exp`. Defaults to 5 seconds. */
+    leewaySeconds?: number;
+}
+declare const DEFAULT_LEEWAY_SECONDS = 5;
+/** Picks the public key for `kid`: the current key, or the previous one while its retirement is in the future. */
+declare function selectVerificationKey(kid: string | undefined, signing: AccessTokenSigningKeys, now: number): string | undefined;
+/**
+ * Verifies an Ed25519 access token. Throws GrpcError(UNAUTHENTICATED) with a short,
+ * key-material-free reason on any failure.
+ */
+declare function verifyAccessToken(token: string, state: AccessTokenVerifierState, options?: AccessTokenVerifyOptions): AccessTokenClaims;
+
+type AccessTokenMode = 'session' | 'jwt';
+interface AccessTokenVerifierSnapshot {
+    mode: AccessTokenMode;
+    strictRevocation: boolean;
+    ready: boolean;
+    tokenVersion: number;
+    /** Current signing key id, if keys are loaded. */
+    kid?: string;
+}
+declare const AUTHENTICATION_CONFIG_UPDATE_CHANNEL = "authentication:config:update";
+declare class AccessTokenVerifier {
+    private readonly grpcSdk;
+    private static instance?;
+    private _mode;
+    private _strictRevocation;
+    private _tokenVersion;
+    private _signing?;
+    private _loaded;
+    private _subscribed;
+    private _generation;
+    private _running;
+    private _retryTimer?;
+    private _refreshTimer?;
+    private _lastRefetch;
+    private _refetching;
+    private _warned;
+    private _listeners;
+    private constructor();
+    static getInstance(grpcSdk: ConduitGrpcSdk): AccessTokenVerifier;
+    /**
+     * Internal, for tests only: stops the verifier, clears all state and drops the singleton.
+     */
+    static resetForTests(): void;
+    private resetState;
+    /** Snapshot of the verifier's observable state. */
+    get state(): AccessTokenVerifierSnapshot;
+    /**
+     * 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: (state: AccessTokenVerifierSnapshot) => void): () => void;
+    private fingerprint;
+    get mode(): AccessTokenMode;
+    get strictRevocation(): boolean;
+    /** True once signing keys have been loaded. */
+    get ready(): boolean;
+    get tokenVersion(): number;
+    /**
+     * 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.
+     */
+    start(): Promise<void>;
+    stop(): void;
+    private attempt;
+    private subscribe;
+    /** Refetches the config from the authentication module; failures keep the previous state. */
+    private refetch;
+    private warnOnce;
+    private static validPem;
+    /**
+     * 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).
+     */
+    private normalizeSigning;
+    private validPreviousKey;
+    private parseTokenVersion;
+    private notifyListeners;
+    /**
+     * 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: unknown): void;
+    /**
+     * 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: string, options?: AccessTokenVerifyOptions): AccessTokenClaims;
+}
+
 declare class ModuleError extends GrpcError {
     debugLogInfo?: string;
     constructor(errorDefinition: ModuleErrorDefinition, debugLogInfo?: string);
 }
 
-export { ConduitActiveSchema, ConduitBoolean, ConduitDate, ConduitJson, ConduitNumber, ConduitObjectId, type ConduitPackageJson, type ConduitPeerWatchEntry, type ConduitPeersManifest, ConduitRelation, type ConduitService, ConduitServiceModule, ConduitString, ConfigController, DEFAULT_STRIP_FIELDS, type ExportModelAdapter, type ExportResult, type ExportableResource, GrpcServer, type ImportModelAdapter, type ImportResult, type ImportResultEntry, ManagedModule, ModuleError, ModuleLifecycleStage, type RequestHandlers, RouteBuilder, type RouterRequestHandler, type RouterRequestHandlerCallback, RoutingManager, type SanitizeForExportOptions, type SocketEventHandler, type SocketRequestHandler, type SocketRequestHandlerCallback, type SocketRequestHandlers, addServiceToServer, containsRedactedMarker, convictConfigParser, createParsedRouterRequest, createServer, exportModel, importModel, initializeSdk, linearBackoffTimeout, linearBackoffTimeoutAsync, merge, readConduitPeersManifest, reconcileStoredModuleConfig, redactSensitiveConfig, restoreRedactedSecrets, sanitizeDocumentsForExport, stableConfigJson, storedConfigsEquivalent, stripInternalFields, wrapFunctionsAsync, wrapGrpcFunctions, wrapRouterGrpcFunction };
+export { AUTHENTICATION_CONFIG_UPDATE_CHANNEL, type AccessTokenMode, type AccessTokenSigningKeys, AccessTokenVerifier, type AccessTokenVerifierSnapshot, type AccessTokenVerifierState, type AccessTokenVerifyOptions, ConduitActiveSchema, ConduitBoolean, ConduitDate, ConduitJson, ConduitNumber, ConduitObjectId, type ConduitPackageJson, type ConduitPeerWatchEntry, type ConduitPeersManifest, ConduitRelation, type ConduitService, ConduitServiceModule, ConduitString, ConfigController, DEFAULT_LEEWAY_SECONDS, DEFAULT_STRIP_FIELDS, type ExportModelAdapter, type ExportResult, type ExportableResource, GrpcServer, type ImportModelAdapter, type ImportResult, type ImportResultEntry, ManagedModule, ModuleError, ModuleLifecycleStage, type RequestHandlers, RouteBuilder, type RouterRequestHandler, type RouterRequestHandlerCallback, RoutingManager, type SanitizeForExportOptions, type SocketEventHandler, type SocketRequestHandler, type SocketRequestHandlerCallback, type SocketRequestHandlers, type UserHydrator, type UserResolver, addServiceToServer, containsRedactedMarker, 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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ConduitSchema, DatabaseProvider, ConduitModel, ConduitSchemaOptions, Query, FindOneOptions, FindManyOptions, AuthzOptions, PopulateAuthzOptions, CountDocumentsOptions, ConduitGrpcSdk, HealthCheckStatus, GrpcRequest, HealthCheckRequest, GrpcCallback, HealthCheckResponse, SetConfigRequest, GrpcResponse, SetConfigResponse, GetExportableResourcesRequest, GetExportableResourcesResponse, ExportResourcesRequest, ExportResourcesResponse, ImportResourcesRequest, ImportResourcesResponse, PeerWatchEdge, TYPE, ConduitNumberValidation, ConduitStringValidation, Params, Context, Cookies, ParsedRouterRequest, UnparsedRouterResponse, ConduitSocketParamTypes, ConduitRouteReturnDefinition, ParsedSocketRequest, UnparsedSocketResponse, Indexable, Router, Admin, ConduitMiddlewareOptions, ConduitRouteOptions, ConduitSocketOptions, ConduitRouteActions, ConduitQueryParams, ConduitUrlParams, ConduitReturn, ConduitRoute, GrpcError, ModuleErrorDefinition } from '@conduitplatform/grpc-sdk';
+import { ConduitSchema, DatabaseProvider, ConduitModel, ConduitSchemaOptions, Query, FindOneOptions, FindManyOptions, AuthzOptions, PopulateAuthzOptions, CountDocumentsOptions, ConduitGrpcSdk, HealthCheckStatus, GrpcRequest, HealthCheckRequest, GrpcCallback, HealthCheckResponse, SetConfigRequest, GrpcResponse, SetConfigResponse, GetExportableResourcesRequest, GetExportableResourcesResponse, ExportResourcesRequest, ExportResourcesResponse, ImportResourcesRequest, ImportResourcesResponse, PeerWatchEdge, TYPE, ConduitNumberValidation, ConduitStringValidation, Params, Context, Cookies, ParsedRouterRequest, Indexable, UnparsedRouterResponse, ConduitSocketParamTypes, ConduitRouteReturnDefinition, ParsedSocketRequest, UnparsedSocketResponse, Router, Admin, ConduitMiddlewareOptions, ConduitRouteOptions, ConduitSocketOptions, ConduitRouteActions, ConduitQueryParams, ConduitUrlParams, ConduitReturn, ConduitRoute, AccessTokenClaims, GrpcError, ModuleErrorDefinition } from '@conduitplatform/grpc-sdk';
 import { EventEmitter } from 'events';
 import { ServerWritableStream, Server } from '@grpc/grpc-js';
 import convict from 'convict';
@@ -345,6 +345,49 @@ declare function wrapGrpcFunctions(functions: {
 
 declare function createParsedRouterRequest(params: Params, urlParams?: Params, queryParams?: Params, bodyParams?: Params, path?: string, headers?: Headers, context?: Context, cookies?: Cookies, rawHeaders?: string[], rawBody?: Buffer): ParsedRouterRequest;
 
+/**
+ * User hydration.
+ *
+ * Client routes guarded by `authMiddleware` / `authMiddleware?` receive `context.user`.
+ * In "session" mode the authentication middleware already sets it. In "jwt" mode the
+ * router only knows the user id (`context.userId`, from a verified access token), so
+ * module-tools fetches the user (through grpcSdk.authentication.getUser, which reads
+ * through a 5s Redis cache) before invoking the handler.
+ *
+ * Opt out per route with `hydrateUser: false` (RouteBuilder.hydrateUser(false)).
+ *
+ * @deprecated The default flips to off in the next major version. Modules are then
+ * expected to call `grpcSdk.authentication.getUser(context.userId)` explicitly.
+ */
+interface UserHydrator {
+    /** True for `authMiddleware?`: a failed lookup leaves the context untouched. */
+    optional: boolean;
+    getUser: (userId: string) => Promise<Indexable>;
+}
+/** Whether the route is guarded by an auth middleware, and if so whether it is the optional form. */
+declare function getAuthMiddlewareKind(routeOptions: Indexable): 'required' | 'optional' | undefined;
+/**
+ * Pure hydration decision: the route has an auth middleware, `hydrateUser` is not false,
+ * and the context carries a `userId` but no `user`. Admin routes must not call this.
+ */
+declare function shouldHydrateUser(routeOptions: Indexable | undefined, context: Indexable | undefined): boolean;
+type UserResolver = (userId: string) => Promise<Indexable>;
+/**
+ * Builds the per-route hydrator for client routes, or undefined when the route never hydrates.
+ * `resolve` is consulted per request (so a resolver registered after route registration still
+ * applies) and returns the lookup function to use, if any.
+ */
+declare function createUserHydrator(routeOptions: Indexable | undefined, resolve: () => UserResolver | undefined): UserHydrator | undefined;
+/** Maps a failed user lookup to the gRPC code returned to the caller. */
+declare function mapHydrationErrorCode(error: unknown): number;
+/**
+ * Sets context.user when needed. For the mandatory form a failed lookup throws a GrpcError:
+ * NOT_FOUND becomes UNAUTHENTICATED; PERMISSION_DENIED and every other gRPC code
+ * (UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, ...) pass through. The optional form
+ * swallows the failure and leaves the context untouched. Failures are logged at warn level.
+ */
+declare function hydrateContextUser(routeOptions: Indexable, context: Indexable, hydrator: UserHydrator): Promise<void>;
+
 type RouterRequestHandler = (call: ParsedRouterRequest) => Promise<UnparsedRouterResponse>;
 type RouterRequestHandlerCallback = (call: ParsedRouterRequest, callback: (response: UnparsedRouterResponse) => void) => Promise<UnparsedRouterResponse | undefined | void>;
 type SocketRequestHandler = (call: ParsedSocketRequest) => Promise<UnparsedSocketResponse>;
@@ -356,7 +399,10 @@ interface SocketEventHandler {
     returnType?: ConduitRouteReturnDefinition;
     handler: SocketRequestHandlers;
 }
-declare function wrapRouterGrpcFunction(fun: RequestHandlers | SocketRequestHandlers, routerType: string): (call: Indexable, callback: any) => void;
+declare function wrapRouterGrpcFunction(fun: RequestHandlers | SocketRequestHandlers, routerType: string, hydration?: {
+    options: Indexable;
+    hydrator: UserHydrator;
+}): (call: Indexable, callback: any) => void;
 
 declare class RoutingController {
     private _routeHandlers;
@@ -372,6 +418,17 @@ declare class RoutingManager {
     private _moduleRoutes;
     static ClientController: RoutingController;
     static AdminController: RoutingController;
+    /** Set by ManagedModule; used to hydrate context.user on client routes. */
+    static grpcSdk?: ConduitGrpcSdk;
+    private static userResolver?;
+    private static warnedNoResolver;
+    /**
+     * 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: UserResolver | undefined): void;
+    private static resolveUser;
     private _routeHandlers;
     private readonly isAdmin;
     constructor(_router: Router | Admin, _server: GrpcServer);
@@ -409,6 +466,13 @@ declare class RouteBuilder {
     rateLimit(maxRequests: number, resetInterval: number): RouteBuilder;
     captureRawBody(capture: boolean): RouteBuilder;
     captureRawHeaders(capture: boolean): RouteBuilder;
+    /**
+     * 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: boolean): RouteBuilder;
     return(name: string, fields: ConduitReturn): RouteBuilder;
     handler(fn: RequestHandlers): RouteBuilder;
     add(): void;
@@ -417,7 +481,12 @@ declare class RouteBuilder {
 
 declare function wrapFunctionsAsync(functions: {
     [name: string]: RequestHandlers | SocketRequestHandlers;
-}, routerType: 'admin' | 'client'): {
+}, routerType: 'admin' | 'client', hydrations?: {
+    [name: string]: {
+        options: Indexable;
+        hydrator: UserHydrator;
+    };
+}): {
     [name: string]: (call: Indexable, callback?: Indexable) => void;
 };
 
@@ -502,9 +571,121 @@ declare function reconcileStoredModuleConfig<T>(args: {
     persisted: boolean;
 }>;
 
+interface AccessTokenSigningKeys {
+    kid: string;
+    /** PEM (SPKI) Ed25519 public key. */
+    publicKey: string;
+    previousKid?: string;
+    previousPublicKey?: string;
+    /** Epoch ms until which the previous key is still accepted. 0 (or unset) means no previous key. */
+    previousRetiredAt?: number;
+}
+interface AccessTokenVerifierState {
+    tokenVersion: number;
+    signing: AccessTokenSigningKeys;
+}
+interface AccessTokenVerifyOptions {
+    /** Client id of the request. When set, it must equal the token's `cid`. */
+    clientId?: string;
+    /** Current time in epoch milliseconds. Defaults to Date.now(). */
+    now?: number;
+    /** Clock skew tolerance for `exp`. Defaults to 5 seconds. */
+    leewaySeconds?: number;
+}
+declare const DEFAULT_LEEWAY_SECONDS = 5;
+/** Picks the public key for `kid`: the current key, or the previous one while its retirement is in the future. */
+declare function selectVerificationKey(kid: string | undefined, signing: AccessTokenSigningKeys, now: number): string | undefined;
+/**
+ * Verifies an Ed25519 access token. Throws GrpcError(UNAUTHENTICATED) with a short,
+ * key-material-free reason on any failure.
+ */
+declare function verifyAccessToken(token: string, state: AccessTokenVerifierState, options?: AccessTokenVerifyOptions): AccessTokenClaims;
+
+type AccessTokenMode = 'session' | 'jwt';
+interface AccessTokenVerifierSnapshot {
+    mode: AccessTokenMode;
+    strictRevocation: boolean;
+    ready: boolean;
+    tokenVersion: number;
+    /** Current signing key id, if keys are loaded. */
+    kid?: string;
+}
+declare const AUTHENTICATION_CONFIG_UPDATE_CHANNEL = "authentication:config:update";
+declare class AccessTokenVerifier {
+    private readonly grpcSdk;
+    private static instance?;
+    private _mode;
+    private _strictRevocation;
+    private _tokenVersion;
+    private _signing?;
+    private _loaded;
+    private _subscribed;
+    private _generation;
+    private _running;
+    private _retryTimer?;
+    private _refreshTimer?;
+    private _lastRefetch;
+    private _refetching;
+    private _warned;
+    private _listeners;
+    private constructor();
+    static getInstance(grpcSdk: ConduitGrpcSdk): AccessTokenVerifier;
+    /**
+     * Internal, for tests only: stops the verifier, clears all state and drops the singleton.
+     */
+    static resetForTests(): void;
+    private resetState;
+    /** Snapshot of the verifier's observable state. */
+    get state(): AccessTokenVerifierSnapshot;
+    /**
+     * 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: (state: AccessTokenVerifierSnapshot) => void): () => void;
+    private fingerprint;
+    get mode(): AccessTokenMode;
+    get strictRevocation(): boolean;
+    /** True once signing keys have been loaded. */
+    get ready(): boolean;
+    get tokenVersion(): number;
+    /**
+     * 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.
+     */
+    start(): Promise<void>;
+    stop(): void;
+    private attempt;
+    private subscribe;
+    /** Refetches the config from the authentication module; failures keep the previous state. */
+    private refetch;
+    private warnOnce;
+    private static validPem;
+    /**
+     * 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).
+     */
+    private normalizeSigning;
+    private validPreviousKey;
+    private parseTokenVersion;
+    private notifyListeners;
+    /**
+     * 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: unknown): void;
+    /**
+     * 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: string, options?: AccessTokenVerifyOptions): AccessTokenClaims;
+}
+
 declare class ModuleError extends GrpcError {
     debugLogInfo?: string;
     constructor(errorDefinition: ModuleErrorDefinition, debugLogInfo?: string);
 }
 
-export { ConduitActiveSchema, ConduitBoolean, ConduitDate, ConduitJson, ConduitNumber, ConduitObjectId, type ConduitPackageJson, type ConduitPeerWatchEntry, type ConduitPeersManifest, ConduitRelation, type ConduitService, ConduitServiceModule, ConduitString, ConfigController, DEFAULT_STRIP_FIELDS, type ExportModelAdapter, type ExportResult, type ExportableResource, GrpcServer, type ImportModelAdapter, type ImportResult, type ImportResultEntry, ManagedModule, ModuleError, ModuleLifecycleStage, type RequestHandlers, RouteBuilder, type RouterRequestHandler, type RouterRequestHandlerCallback, RoutingManager, type SanitizeForExportOptions, type SocketEventHandler, type SocketRequestHandler, type SocketRequestHandlerCallback, type SocketRequestHandlers, addServiceToServer, containsRedactedMarker, convictConfigParser, createParsedRouterRequest, createServer, exportModel, importModel, initializeSdk, linearBackoffTimeout, linearBackoffTimeoutAsync, merge, readConduitPeersManifest, reconcileStoredModuleConfig, redactSensitiveConfig, restoreRedactedSecrets, sanitizeDocumentsForExport, stableConfigJson, storedConfigsEquivalent, stripInternalFields, wrapFunctionsAsync, wrapGrpcFunctions, wrapRouterGrpcFunction };
+export { AUTHENTICATION_CONFIG_UPDATE_CHANNEL, type AccessTokenMode, type AccessTokenSigningKeys, AccessTokenVerifier, type AccessTokenVerifierSnapshot, type AccessTokenVerifierState, type AccessTokenVerifyOptions, ConduitActiveSchema, ConduitBoolean, ConduitDate, ConduitJson, ConduitNumber, ConduitObjectId, type ConduitPackageJson, type ConduitPeerWatchEntry, type ConduitPeersManifest, ConduitRelation, type ConduitService, ConduitServiceModule, ConduitString, ConfigController, DEFAULT_LEEWAY_SECONDS, DEFAULT_STRIP_FIELDS, type ExportModelAdapter, type ExportResult, type ExportableResource, GrpcServer, type ImportModelAdapter, type ImportResult, type ImportResultEntry, ManagedModule, ModuleError, ModuleLifecycleStage, type RequestHandlers, RouteBuilder, type RouterRequestHandler, type RouterRequestHandlerCallback, RoutingManager, type SanitizeForExportOptions, type SocketEventHandler, type SocketRequestHandler, type SocketRequestHandlerCallback, type SocketRequestHandlers, type UserHydrator, type UserResolver, addServiceToServer, containsRedactedMarker, 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 };