alepha 0.20.2 → 0.20.4

package/dist/api/users/index.d.ts

@@ -1,5 +1,5 @@
 import * as _$alepha from "alepha";
-import { Alepha, AlephaError, Page, PageQuery, Primitive, Static, StaticEncode, TNull, TObject, TOptional, TSchema, TUnion } from "alepha";
+import { Alepha, AlephaError, Page, PageQuery, Primitive, SchemaValidator, Static, StaticEncode, TNull, TObject, TOptional, TSchema, TUnion } from "alepha";
 import { AuditService, CreateAudit } from "alepha/api/audits";
 import * as _$alepha_bucket0 from "alepha/bucket";
 import { CryptoProvider, IssuerPrimitive, IssuerPrimitiveOptions, UserAccount } from "alepha/security";
@@ -71,9 +71,112 @@ declare const realmAuthSettingsAtom: _$alepha.Atom<_$alepha.TObject<{
     accountMaxAttempts: _$alepha.TInteger;
     windowMs: _$alepha.TInteger;
   }>;
+  refreshToken: _$alepha.TObject<{
+    expirationIdle: _$alepha.TOptional<_$alepha.TInteger>;
+  }>;
 }>, "alepha.api.users.realmAuthSettings">;
 type RealmAuthSettings = Static<typeof realmAuthSettingsAtom.schema>;
 //#endregion
+//#region ../../src/api/users/audits/UserAudits.d.ts
+type AuditContext = Omit<CreateAudit, "type" | "action">;
+/**
+ * User-specific audit wrapper service.
+ *
+ * This service wraps the core AuditService to provide user-related audit logging.
+ *
+ * Declared as a module variant — not auto-injected. It is instantiated
+ * lazily the first time something calls `alepha.inject(UserAudits)`.
+ */
+declare class UserAudits {
+  protected readonly auditService: AuditService;
+  /**
+   * Record a user-related audit event.
+   */
+  recordUser(action: "create" | "update" | "delete" | "role_change" | "enable" | "disable", context: AuditContext): Promise<{
+    description?: string | undefined;
+    userId?: string | undefined;
+    userRealm?: string | undefined;
+    userEmail?: string | undefined;
+    resourceType?: string | undefined;
+    resourceId?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+    ipAddress?: string | undefined;
+    userAgent?: string | undefined;
+    sessionId?: string | undefined;
+    requestId?: string | undefined;
+    errorMessage?: string | undefined;
+    type: string;
+    id: string;
+    createdAt: string;
+    action: string;
+    severity: "info" | "warning" | "critical";
+    success: boolean;
+  }>;
+  /**
+   * Record an authentication-related audit event.
+   */
+  recordAuth(action: "login" | "logout" | "login_failed" | "token_refresh", context: AuditContext): Promise<{
+    description?: string | undefined;
+    userId?: string | undefined;
+    userRealm?: string | undefined;
+    userEmail?: string | undefined;
+    resourceType?: string | undefined;
+    resourceId?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+    ipAddress?: string | undefined;
+    userAgent?: string | undefined;
+    sessionId?: string | undefined;
+    requestId?: string | undefined;
+    errorMessage?: string | undefined;
+    type: string;
+    id: string;
+    createdAt: string;
+    action: string;
+    severity: "info" | "warning" | "critical";
+    success: boolean;
+  }>;
+  /**
+   * Record a generic audit event.
+   */
+  record(category: string, action: string, context: AuditContext): Promise<{
+    description?: string | undefined;
+    userId?: string | undefined;
+    userRealm?: string | undefined;
+    userEmail?: string | undefined;
+    resourceType?: string | undefined;
+    resourceId?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+    ipAddress?: string | undefined;
+    userAgent?: string | undefined;
+    sessionId?: string | undefined;
+    requestId?: string | undefined;
+    errorMessage?: string | undefined;
+    type: string;
+    id: string;
+    createdAt: string;
+    action: string;
+    severity: "info" | "warning" | "critical";
+    success: boolean;
+  }>;
+}
+//#endregion
+//#region ../../src/api/users/buckets/UserBuckets.d.ts
+/**
+ * User-specific file storage wrapper service.
+ *
+ * This service provides file storage for user-related files such as:
+ * - User avatars/profile pictures
+ *
+ * Declared as a module variant — not auto-injected. It is instantiated
+ * lazily the first time something calls `alepha.inject(UserBuckets)`.
+ */
+declare class UserBuckets {
+  /**
+   * Bucket for user avatar storage.
+   */
+  readonly avatars: _$alepha_bucket0.BucketPrimitive;
+}
+//#endregion
 //#region ../../src/orm/core/schemas/insertSchema.d.ts
 /**
  * Transforms a TObject schema for insert operations.
@@ -355,6 +458,19 @@ declare class DbError extends AlephaError {
   constructor(message: string, cause?: unknown);
 }
 //#endregion
+//#region ../../src/orm/core/helpers/pgAttr.d.ts
+/**
+ * Type representation.
+ */
+type PgAttr<T extends TSchema, TAttr extends PgSymbolKeys> = T & { [K in TAttr]: PgSymbols[K] };
+interface PgAttrField {
+  key: string;
+  type: TSchema;
+  data: any;
+  nested?: any[];
+  one?: boolean;
+}
+//#endregion
 //#region ../../src/orm/core/interfaces/FilterOperators.d.ts
 interface FilterOperators<TValue> {
   /**
@@ -901,19 +1017,6 @@ type PgQueryWhereConditions<T extends TObject, Relations extends PgRelationMap<T
 };
 type PgQueryWhereRelations<Relations extends PgRelationMap<TObject> | undefined = undefined> = Relations extends PgRelationMap<TObject> ? { [K in keyof Relations]?: PgQueryWhere<Relations[K]["join"]["schema"], Relations[K]["with"]> } : {};
 //#endregion
-//#region ../../src/orm/core/helpers/pgAttr.d.ts
-/**
- * Type representation.
- */
-type PgAttr<T extends TSchema, TAttr extends PgSymbolKeys> = T & { [K in TAttr]: PgSymbols[K] };
-interface PgAttrField {
-  key: string;
-  type: TSchema;
-  data: any;
-  nested?: any[];
-  one?: boolean;
-}
-//#endregion
 //#region ../../src/orm/core/interfaces/AggregateQuery.d.ts
 type AggregateOp = "count" | "sum" | "avg" | "min" | "max";
 /**
@@ -985,35 +1088,6 @@ interface AggregateQuery<T extends TObject, S extends AggregateSelect<T>> {
   offset?: number;
 }
 //#endregion
-//#region ../../src/orm/core/primitives/$view.d.ts
-interface ViewPrimitiveOptions<T extends TObject> {
-  /**
-   * The database view name.
-   */
-  name: string;
-  /**
-   * TypeBox schema defining the view's columns.
-   */
-  schema: T;
-  /**
-   * SQL query that defines the view.
-   */
-  query: SQL;
-  /**
-   * Whether this is a materialized view (PostgreSQL only).
-   * Materialized views store results on disk and can be refreshed.
-   */
-  materialized?: boolean;
-}
-declare class ViewPrimitive<T extends TObject = TObject> {
-  readonly options: ViewPrimitiveOptions<T>;
-  readonly isView = true;
-  constructor(options: ViewPrimitiveOptions<T>);
-  get name(): string;
-  get schema(): T;
-  get materialized(): boolean;
-}
-//#endregion
 //#region ../../src/orm/core/providers/DbCacheProvider.d.ts
 /**
  * Database query cache using a simple in-memory Map.
@@ -1097,13 +1171,6 @@ declare abstract class ModelBuilder {
     schemas: Map<string, unknown>;
     schema: string;
   }): void;
-  /**
-   * Build a view from a view primitive.
-   */
-  abstract buildView(view: ViewPrimitive, options: {
-    tables: Map<string, unknown>;
-    schema: string;
-  }): void;
   /**
    * Build a sequence from a sequence primitive.
    */
@@ -6126,7 +6193,6 @@ declare abstract class DatabaseProvider {
   protected parseOperation(sql: string): string;
   table<T extends TObject>(entity: EntityPrimitive<T>): PgTableWithColumns<SchemaToTableConfig<T>>;
   registerEntity(entity: EntityPrimitive): void;
-  registerView(view: ViewPrimitive): void;
   registerSequence(sequence: SequencePrimitive): void;
   /**
    * Rebuild all models into fresh maps using a different schema.
@@ -6255,6 +6321,7 @@ interface PgJoin {
 //#endregion
 //#region ../../src/orm/core/services/PgRelationManager.d.ts
 declare class PgRelationManager {
+  protected readonly schemaValidator: SchemaValidator;
   /**
    * Recursively build joins for the query builder based on the relations map
    */
@@ -6305,10 +6372,6 @@ declare abstract class Repository$1<T extends TObject> {
    * Get SQL table name. (from Drizzle table object)
    */
   get tableName(): string;
-  /**
-   * Whether this repository is backed by a view (read-only).
-   */
-  get isReadOnly(): boolean;
   /**
    * Getter for the database connection from the database provider.
    *
@@ -6583,14 +6646,6 @@ declare abstract class Repository$1<T extends TObject> {
    * Clean a row with joins recursively
    */
   protected cleanWithJoins<T extends TObject>(row: Record<string, unknown>, schema: T, joins: PgJoin[], parentPath?: string): Static<T>;
-  /**
-   * Throw if this repository is read-only (backed by a view).
-   */
-  protected assertWritable(): void;
-  /**
-   * Refresh a materialized view. PostgreSQL only.
-   */
-  refresh(): Promise<void>;
   /**
    * Build a cache key from method name and query parameters.
    */
@@ -6695,163 +6750,6 @@ declare module "alepha" {
   interface Env extends Partial<Static<typeof databaseEnvSchema>> {}
 } //# sourceMappingURL=databaseEnvSchema.d.ts.map
 //#endregion
-//#region ../../src/api/users/audits/UserAudits.d.ts
-type AuditContext = Omit<CreateAudit, "type" | "action">;
-/**
- * User-specific audit wrapper service.
- *
- * This service wraps the core AuditService to provide user-related audit logging.
- *
- * Declared as a module variant — not auto-injected. It is instantiated
- * lazily the first time something calls `alepha.inject(UserAudits)`.
- */
-declare class UserAudits {
-  protected readonly auditService: AuditService;
-  /**
-   * Record a user-related audit event.
-   */
-  recordUser(action: "create" | "update" | "delete" | "role_change" | "enable" | "disable", context: AuditContext): Promise<{
-    description?: string | undefined;
-    userId?: string | undefined;
-    userRealm?: string | undefined;
-    userEmail?: string | undefined;
-    resourceType?: string | undefined;
-    resourceId?: string | undefined;
-    metadata?: _$typebox.StaticRecord<[], "Decode", {}, {
-      id: PgAttr<PgAttr<_$alepha.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
-      createdAt: PgAttr<PgAttr<_$alepha.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
-      type: _$alepha.TString;
-      action: _$alepha.TString;
-      severity: PgAttr<_$alepha.TUnsafe<"info" | "warning" | "critical">, typeof PG_DEFAULT>;
-      userId: _$alepha.TOptional<_$alepha.TString>;
-      userRealm: _$alepha.TOptional<_$alepha.TString>;
-      userEmail: _$alepha.TOptional<_$alepha.TString>;
-      resourceType: _$alepha.TOptional<_$alepha.TString>;
-      resourceId: _$alepha.TOptional<_$alepha.TString>;
-      description: _$alepha.TOptional<_$alepha.TString>;
-      metadata: _$alepha.TOptional<_$alepha.TRecord<string, _$alepha.TAny>>;
-      ipAddress: _$alepha.TOptional<_$alepha.TString>;
-      userAgent: _$alepha.TOptional<_$alepha.TString>;
-      sessionId: _$alepha.TOptional<_$alepha.TString>;
-      requestId: _$alepha.TOptional<_$alepha.TString>;
-      success: PgAttr<_$alepha.TBoolean, typeof PG_DEFAULT>;
-      errorMessage: _$alepha.TOptional<_$alepha.TString>;
-    }, string, _$alepha.TAny> | undefined;
-    ipAddress?: string | undefined;
-    userAgent?: string | undefined;
-    sessionId?: string | undefined;
-    requestId?: string | undefined;
-    errorMessage?: string | undefined;
-    type: string;
-    id: string;
-    createdAt: string;
-    action: string;
-    severity: "info" | "warning" | "critical";
-    success: boolean;
-  }>;
-  /**
-   * Record an authentication-related audit event.
-   */
-  recordAuth(action: "login" | "logout" | "login_failed" | "token_refresh", context: AuditContext): Promise<{
-    description?: string | undefined;
-    userId?: string | undefined;
-    userRealm?: string | undefined;
-    userEmail?: string | undefined;
-    resourceType?: string | undefined;
-    resourceId?: string | undefined;
-    metadata?: _$typebox.StaticRecord<[], "Decode", {}, {
-      id: PgAttr<PgAttr<_$alepha.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
-      createdAt: PgAttr<PgAttr<_$alepha.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
-      type: _$alepha.TString;
-      action: _$alepha.TString;
-      severity: PgAttr<_$alepha.TUnsafe<"info" | "warning" | "critical">, typeof PG_DEFAULT>;
-      userId: _$alepha.TOptional<_$alepha.TString>;
-      userRealm: _$alepha.TOptional<_$alepha.TString>;
-      userEmail: _$alepha.TOptional<_$alepha.TString>;
-      resourceType: _$alepha.TOptional<_$alepha.TString>;
-      resourceId: _$alepha.TOptional<_$alepha.TString>;
-      description: _$alepha.TOptional<_$alepha.TString>;
-      metadata: _$alepha.TOptional<_$alepha.TRecord<string, _$alepha.TAny>>;
-      ipAddress: _$alepha.TOptional<_$alepha.TString>;
-      userAgent: _$alepha.TOptional<_$alepha.TString>;
-      sessionId: _$alepha.TOptional<_$alepha.TString>;
-      requestId: _$alepha.TOptional<_$alepha.TString>;
-      success: PgAttr<_$alepha.TBoolean, typeof PG_DEFAULT>;
-      errorMessage: _$alepha.TOptional<_$alepha.TString>;
-    }, string, _$alepha.TAny> | undefined;
-    ipAddress?: string | undefined;
-    userAgent?: string | undefined;
-    sessionId?: string | undefined;
-    requestId?: string | undefined;
-    errorMessage?: string | undefined;
-    type: string;
-    id: string;
-    createdAt: string;
-    action: string;
-    severity: "info" | "warning" | "critical";
-    success: boolean;
-  }>;
-  /**
-   * Record a generic audit event.
-   */
-  record(category: string, action: string, context: AuditContext): Promise<{
-    description?: string | undefined;
-    userId?: string | undefined;
-    userRealm?: string | undefined;
-    userEmail?: string | undefined;
-    resourceType?: string | undefined;
-    resourceId?: string | undefined;
-    metadata?: _$typebox.StaticRecord<[], "Decode", {}, {
-      id: PgAttr<PgAttr<_$alepha.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
-      createdAt: PgAttr<PgAttr<_$alepha.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
-      type: _$alepha.TString;
-      action: _$alepha.TString;
-      severity: PgAttr<_$alepha.TUnsafe<"info" | "warning" | "critical">, typeof PG_DEFAULT>;
-      userId: _$alepha.TOptional<_$alepha.TString>;
-      userRealm: _$alepha.TOptional<_$alepha.TString>;
-      userEmail: _$alepha.TOptional<_$alepha.TString>;
-      resourceType: _$alepha.TOptional<_$alepha.TString>;
-      resourceId: _$alepha.TOptional<_$alepha.TString>;
-      description: _$alepha.TOptional<_$alepha.TString>;
-      metadata: _$alepha.TOptional<_$alepha.TRecord<string, _$alepha.TAny>>;
-      ipAddress: _$alepha.TOptional<_$alepha.TString>;
-      userAgent: _$alepha.TOptional<_$alepha.TString>;
-      sessionId: _$alepha.TOptional<_$alepha.TString>;
-      requestId: _$alepha.TOptional<_$alepha.TString>;
-      success: PgAttr<_$alepha.TBoolean, typeof PG_DEFAULT>;
-      errorMessage: _$alepha.TOptional<_$alepha.TString>;
-    }, string, _$alepha.TAny> | undefined;
-    ipAddress?: string | undefined;
-    userAgent?: string | undefined;
-    sessionId?: string | undefined;
-    requestId?: string | undefined;
-    errorMessage?: string | undefined;
-    type: string;
-    id: string;
-    createdAt: string;
-    action: string;
-    severity: "info" | "warning" | "critical";
-    success: boolean;
-  }>;
-}
-//#endregion
-//#region ../../src/api/users/buckets/UserBuckets.d.ts
-/**
- * User-specific file storage wrapper service.
- *
- * This service provides file storage for user-related files such as:
- * - User avatars/profile pictures
- *
- * Declared as a module variant — not auto-injected. It is instantiated
- * lazily the first time something calls `alepha.inject(UserBuckets)`.
- */
-declare class UserBuckets {
-  /**
-   * Bucket for user avatar storage.
-   */
-  readonly avatars: _$alepha_bucket0.BucketPrimitive;
-}
-//#endregion
 //#region ../../src/api/users/entities/identities.d.ts
 declare const identities: _$alepha_orm0.EntityPrimitive<_$alepha.TObject<{
   id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$alepha.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
@@ -6875,6 +6773,12 @@ declare const sessions: _$alepha_orm0.EntityPrimitive<_$alepha.TObject<{
   refreshToken: _$alepha.TString;
   userId: _$alepha_orm0.PgAttr<_$alepha.TString, typeof _$alepha_orm0.PG_REF>;
   expiresAt: _$alepha.TString;
+  /**
+   * Last time the session was used to refresh an access token.
+   * Used by realm `refreshToken.expirationIdle` to invalidate idle sessions.
+   * `null` on existing rows pre-migration — falls back to `createdAt`.
+   */
+  lastUsedAt: _$alepha.TOptional<_$alepha.TString>;
   ip: _$alepha.TOptional<_$alepha.TString>;
   userAgent: _$alepha.TOptional<_$alepha.TObject<{
     os: _$alepha.TString;
@@ -7047,6 +6951,7 @@ declare class RealmProvider {
     refreshToken: _$alepha.TString;
     userId: _$alepha_orm0.PgAttr<_$alepha.TString, typeof _$alepha_orm0.PG_REF>;
     expiresAt: _$alepha.TString;
+    lastUsedAt: _$alepha.TOptional<_$alepha.TString>;
     ip: _$alepha.TOptional<_$alepha.TString>;
     userAgent: _$alepha.TOptional<_$alepha.TObject<{
       os: _$alepha.TString;
@@ -7211,6 +7116,7 @@ declare class SessionCrudService {
     refreshToken: _$alepha.TString;
     userId: _$alepha_orm0.PgAttr<_$alepha.TString, typeof _$alepha_orm0.PG_REF>;
     expiresAt: _$alepha.TString;
+    lastUsedAt: _$alepha.TOptional<_$alepha.TString>;
     ip: _$alepha.TOptional<_$alepha.TString>;
     userAgent: _$alepha.TOptional<_$alepha.TObject<{
       os: _$alepha.TString;
@@ -7351,7 +7257,7 @@ declare const createUserSchema: _$alepha.TObject<{
   createdAt: _$alepha.TOptional<PgAttr<PgAttr<_$alepha.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>>;
   updatedAt: _$alepha.TOptional<PgAttr<PgAttr<_$alepha.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>>;
   username: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
-  roles: _$alepha.TOptional<_$alepha.TArray<_$alepha.TString>>;
+  roles: _$alepha.TOptional<PgAttr<_$alepha.TArray<_$alepha.TString>, typeof PG_DEFAULT>>;
   firstName: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
   lastName: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
   picture: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
@@ -7366,7 +7272,7 @@ declare const updateUserSchema: _$alepha.TObject<{
   email: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
   phoneNumber: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
   realm: _$alepha.TOptional<PgAttr<_$alepha.TString, typeof PG_DEFAULT>>;
-  roles: _$alepha.TOptional<_$alepha.TArray<_$alepha.TString>>;
+  roles: _$alepha.TOptional<PgAttr<_$alepha.TArray<_$alepha.TString>, typeof PG_DEFAULT>>;
   firstName: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
   lastName: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
   picture: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
@@ -7383,7 +7289,6 @@ declare const userQuerySchema: _$alepha.TObject<{
   enabled: _$alepha.TOptional<_$alepha.TBoolean>;
   emailVerified: _$alepha.TOptional<_$alepha.TBoolean>;
   roles: _$alepha.TOptional<_$alepha.TArray<_$alepha.TString>>;
-  query: _$alepha.TOptional<_$alepha.TString>;
 }>;
 type UserQuery = Static<typeof userQuerySchema>;
 //#endregion
@@ -7468,7 +7373,6 @@ declare class AdminUserController {
       enabled: _$alepha.TOptional<_$alepha.TBoolean>;
       emailVerified: _$alepha.TOptional<_$alepha.TBoolean>;
       roles: _$alepha.TOptional<_$alepha.TArray<_$alepha.TString>>;
-      query: _$alepha.TOptional<_$alepha.TString>;
       userRealmName: _$alepha.TOptional<_$alepha.TString>;
     }>;
     response: _$alepha.TPage<_$alepha.TObject<{
@@ -7533,7 +7437,7 @@ declare class AdminUserController {
       createdAt: _$alepha.TOptional<PgAttr<PgAttr<_$alepha.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>>;
       updatedAt: _$alepha.TOptional<PgAttr<PgAttr<_$alepha.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>>;
       username: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
-      roles: _$alepha.TOptional<_$alepha.TArray<_$alepha.TString>>;
+      roles: _$alepha.TOptional<PgAttr<_$alepha.TArray<_$alepha.TString>, typeof PG_DEFAULT>>;
       firstName: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
       lastName: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
       picture: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
@@ -7573,7 +7477,7 @@ declare class AdminUserController {
       email: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
       phoneNumber: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
       realm: _$alepha.TOptional<PgAttr<_$alepha.TString, typeof PG_DEFAULT>>;
-      roles: _$alepha.TOptional<_$alepha.TArray<_$alepha.TString>>;
+      roles: _$alepha.TOptional<PgAttr<_$alepha.TArray<_$alepha.TString>, typeof PG_DEFAULT>>;
       firstName: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
       lastName: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
       picture: _$alepha.TOptional<_$alepha.TOptional<_$alepha.TString>>;
@@ -7665,6 +7569,9 @@ declare class RealmController {
           accountMaxAttempts: _$alepha.TInteger;
           windowMs: _$alepha.TInteger;
         }>;
+        refreshToken: _$alepha.TObject<{
+          expirationIdle: _$alepha.TOptional<_$alepha.TInteger>;
+        }>;
       }>;
       realmName: _$alepha.TString;
       authenticationMethods: _$alepha.TArray<_$alepha.TObject<{
@@ -7760,6 +7667,7 @@ declare class CredentialService {
     refreshToken: _$alepha.TString;
     userId: PgAttr<_$alepha.TString, typeof PG_REF>;
     expiresAt: _$alepha.TString;
+    lastUsedAt: _$alepha.TOptional<_$alepha.TString>;
     ip: _$alepha.TOptional<_$alepha.TString>;
     userAgent: _$alepha.TOptional<_$alepha.TObject<{
       os: _$alepha.TString;
@@ -8138,6 +8046,7 @@ declare class UserJobs {
     refreshToken: _$alepha.TString;
     userId: _$alepha_orm0.PgAttr<_$alepha.TString, typeof _$alepha_orm0.PG_REF>;
     expiresAt: _$alepha.TString;
+    lastUsedAt: _$alepha.TOptional<_$alepha.TString>;
     ip: _$alepha.TOptional<_$alepha.TString>;
     userAgent: _$alepha.TOptional<_$alepha.TObject<{
       os: _$alepha.TString;
@@ -8145,10 +8054,18 @@ declare class UserJobs {
       device: _$alepha.TUnsafe<"MOBILE" | "DESKTOP" | "TABLET">;
     }>>;
   }>>;
+  protected readonly realmProvider: RealmProvider;
   /**
    * Purge expired sessions from the database.
    *
-   * Runs hourly (at :00) and deletes sessions whose `expiresAt` has passed.
+   * Runs hourly (at :00) and deletes:
+   * - sessions whose absolute `expiresAt` has passed
+   * - sessions whose `lastUsedAt` exceeds the realm's `refreshToken.expirationIdle`
+   *   (when configured). Falls back to `createdAt` for sessions without a
+   *   recorded `lastUsedAt`.
+   *
+   * The idle sweep is best-effort cleanup — runtime enforcement happens in
+   * `SessionService.refreshSession()`.
    */
   readonly purgeExpiredSessions: _$alepha_api_jobs0.JobPrimitive<_$alepha.TSchema>;
 }
@@ -8205,6 +8122,9 @@ declare const realmConfigSchema: _$alepha.TObject<{
       accountMaxAttempts: _$alepha.TInteger;
       windowMs: _$alepha.TInteger;
     }>;
+    refreshToken: _$alepha.TObject<{
+      expirationIdle: _$alepha.TOptional<_$alepha.TInteger>;
+    }>;
   }>;
   realmName: _$alepha.TString;
   authenticationMethods: _$alepha.TArray<_$alepha.TObject<{
@@ -8313,6 +8233,7 @@ declare class SessionService {
     refreshToken: _$alepha.TString;
     userId: PgAttr<_$alepha.TString, typeof PG_REF>;
     expiresAt: _$alepha.TString;
+    lastUsedAt: _$alepha.TOptional<_$alepha.TString>;
     ip: _$alepha.TOptional<_$alepha.TString>;
     userAgent: _$alepha.TOptional<_$alepha.TObject<{
       os: _$alepha.TString;