alepha 0.20.3 → 0.20.4

package/src/api/parameters/services/ParameterProvider.ts

@@ -3,10 +3,10 @@ import {
   $inject,
   Alepha,
   AlephaError,
+  SchemaValidator,
   type Static,
   type TObject,
   t,
-  Value,
 } from "alepha";
 import { CryptoProvider } from "alepha/crypto";
 import { DateTimeProvider } from "alepha/datetime";
@@ -49,6 +49,7 @@ export class ParameterProvider {
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly crypto = $inject(CryptoProvider);
   protected readonly lockProvider = $inject(LockProvider);
+  protected readonly schemaValidator = $inject(SchemaValidator);
   protected readonly repo = $repository(parameters);
 
   /**
@@ -757,7 +758,7 @@ export class ParameterProvider {
     if (param.options.migrate) {
       try {
         const migrated = param.options.migrate(dbValue);
-        if (Value.Check(schema, migrated)) {
+        if (this.isValid(schema, migrated)) {
           if (JSON.stringify(migrated) === JSON.stringify(dbValue)) {
             return null;
           }
@@ -785,7 +786,7 @@ export class ParameterProvider {
       schemaKeys,
     );
 
-    if (Value.Check(schema, stripped)) {
+    if (this.isValid(schema, stripped)) {
       if (JSON.stringify(stripped) === JSON.stringify(dbValue)) {
         return null;
       }
@@ -805,7 +806,7 @@ export class ParameterProvider {
       schemaKeys,
     );
 
-    if (Value.Check(schema, merged)) {
+    if (this.isValid(schema, merged)) {
       return {
         value: merged,
         description: "Auto-migrated: merged with defaults",
@@ -857,6 +858,22 @@ export class ParameterProvider {
     }
   }
 
+  /**
+   * Probe whether a value matches the schema, without throwing or mutating.
+   */
+  protected isValid(schema: TObject, value: unknown): boolean {
+    try {
+      this.schemaValidator.validate(schema, value, {
+        trim: false,
+        nullToUndefined: false,
+        deleteUndefined: false,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Return a new object containing only keys present in the schema.
    */

package/src/api/users/__tests__/SessionService.spec.ts

@@ -916,4 +916,103 @@ describe("alepha/api/users - SessionService.refreshSession", () => {
       sessionService.refreshSession(refreshToken),
     ).rejects.toThrowError();
   });
+
+  describe("refresh-token idle timeout", () => {
+    it("should refresh successfully when used within the idle window", async ({
+      expect,
+    }) => {
+      const { sessionService, userService, alepha, dateTimeProvider } =
+        await setup();
+
+      const realmProvider = alepha.inject(RealmProvider);
+      realmProvider.register("idle-ok", {
+        settings: {
+          refreshToken: { expirationIdle: 60 * 60 * 1000 }, // 1 hour
+        } as never,
+      });
+
+      const user = await userService.users("idle-ok").create({
+        realm: "idle-ok",
+        email: "idle-ok@example.com",
+        roles: ["user"],
+      });
+
+      const { refreshToken } = await sessionService.createSession(
+        user,
+        24 * 3600,
+        "idle-ok",
+      );
+
+      // Half the idle window — still well inside.
+      await dateTimeProvider.travel(30, "minutes");
+
+      const result = await sessionService.refreshSession(
+        refreshToken,
+        "idle-ok",
+      );
+      expect(result.user.id).toBe(user.id);
+    });
+
+    it("should reject refresh and delete session when idle window is exceeded", async ({
+      expect,
+    }) => {
+      const { sessionService, userService, alepha, dateTimeProvider } =
+        await setup();
+
+      const realmProvider = alepha.inject(RealmProvider);
+      realmProvider.register("idle-strict", {
+        settings: {
+          refreshToken: { expirationIdle: 5 * 60 * 1000 }, // 5 minutes
+        } as never,
+      });
+
+      const user = await userService.users("idle-strict").create({
+        realm: "idle-strict",
+        email: "idle-strict@example.com",
+        roles: ["user"],
+      });
+
+      const { refreshToken } = await sessionService.createSession(
+        user,
+        7 * 24 * 3600, // 7 day absolute expiry — well beyond idle threshold
+        "idle-strict",
+      );
+
+      // Idle past the threshold (but absolute expiry is still days away).
+      await dateTimeProvider.travel(10, "minutes");
+
+      await expect(
+        sessionService.refreshSession(refreshToken, "idle-strict"),
+      ).rejects.toThrowError(UnauthorizedError);
+
+      // Session deleted — second refresh fails too (row gone).
+      await expect(
+        sessionService.refreshSession(refreshToken, "idle-strict"),
+      ).rejects.toThrowError();
+    });
+
+    it("should not enforce idle when expirationIdle is undefined (default)", async ({
+      expect,
+    }) => {
+      const { sessionService, userService, dateTimeProvider } = await setup();
+
+      const user = await userService.users().create({
+        username: "idle-defaultuser",
+        email: "idle-default@example.com",
+        roles: ["user"],
+      });
+
+      const { refreshToken } = await sessionService.createSession(
+        user,
+        7 * 24 * 3600,
+      );
+
+      // Travel days into the future. With no idleTtl configured, refresh
+      // should still succeed (only absolute expiresAt matters).
+      await dateTimeProvider.travel(3, "days");
+
+      const result = await sessionService.refreshSession(refreshToken);
+      expect(result.user.id).toBe(user.id);
+    });
+  });
 });

package/src/api/users/__tests__/UserJobs.spec.ts

@@ -5,7 +5,9 @@ import { AlephaOrmPostgres } from "alepha/orm/postgres";
 import { describe, test } from "vitest";
 import { sessions } from "../entities/sessions.ts";
 import { users } from "../entities/users.ts";
+import { AlephaApiUsers } from "../index.ts";
 import { UserJobs } from "../jobs/UserJobs.ts";
+import { RealmProvider } from "../providers/RealmProvider.ts";
 
 describe("UserJobs", () => {
   describe("purgeExpiredSessions", () => {
@@ -93,5 +95,70 @@ describe("UserJobs", () => {
 
       expect(await repos.sessionRepository.findMany()).toHaveLength(1);
     });
+
+    test("purges idle sessions when expirationIdle is configured", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create()
+        .with(AlephaOrmPostgres)
+        .with(AlephaApiJobs)
+        .with(AlephaApiUsers);
+
+      class TestRepositories {
+        userRepository = $repository(users);
+        sessionRepository = $repository(sessions);
+      }
+
+      const userJobs = alepha.inject(UserJobs);
+      const repos = alepha.inject(TestRepositories);
+      const realmProvider = alepha.inject(RealmProvider);
+      realmProvider.register("default", {
+        settings: {
+          refreshToken: { expirationIdle: 5 * 60 * 1000 }, // 5 minutes
+        } as never,
+      });
+      await alepha.start();
+
+      const user = await repos.userRepository.create({
+        email: "idle-sweep@example.com",
+      });
+
+      const farFuture = new Date(
+        Date.now() + 30 * 24 * 60 * 60 * 1000,
+      ).toISOString();
+      const oldUsed = new Date(Date.now() - 30 * 60 * 1000).toISOString(); // 30 min ago
+      const recentUsed = new Date(Date.now() - 60 * 1000).toISOString(); // 1 min ago
+
+      // Idle by lastUsedAt — should be purged (lastUsedAt > 5 min ago).
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: farFuture,
+        lastUsedAt: oldUsed,
+      });
+
+      // Recently used — within idle window, should remain.
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: farFuture,
+        lastUsedAt: recentUsed,
+      });
+
+      // Pre-migration row (lastUsedAt null) with old createdAt — should be
+      // purged via createdAt fallback. We can't directly set createdAt via
+      // create() (auto-managed), so simulate by creating a row and then
+      // updating lastUsedAt to null while the row is fresh — the createdAt
+      // fallback will not trip yet (createdAt is now). Skip this case in this
+      // test; covered logically by the deleteMany filter shape.
+
+      expect(await repos.sessionRepository.findMany()).toHaveLength(2);
+
+      await userJobs.purgeExpiredSessions.trigger();
+
+      const remaining = await repos.sessionRepository.findMany();
+      expect(remaining).toHaveLength(1);
+      expect(remaining[0].lastUsedAt).toBe(recentUsed);
+    });
   });
 });

package/src/api/users/atoms/realmAuthSettingsAtom.ts

@@ -121,6 +121,18 @@ export const realmAuthSettingsAtom = $atom({
         minimum: 1000,
       }),
     }),
+    refreshToken: t.object({
+      expirationIdle: t.optional(
+        t.integer({
+          description:
+            "Maximum time in milliseconds a refresh token may stay unused before being invalidated. " +
+            "When set, sessions whose last refresh is older than this window are rejected and deleted, " +
+            "even if the absolute `expiresAt` has not been reached. Recommended for SaaS auth posture " +
+            "(SOC2/ISO27001). Leave undefined to disable idle invalidation (default).",
+          minimum: 1000,
+        }),
+      ),
+    }),
   }),
   default: {
     // for a fresh hello world setup, we accept registration and email login
@@ -149,6 +161,9 @@ export const realmAuthSettingsAtom = $atom({
       accountMaxAttempts: 5,
       windowMs: 15 * 60 * 1000,
     },
+    refreshToken: {
+      // expirationIdle: undefined — opt-in
+    },
   },
 });
 

package/src/api/users/entities/sessions.ts

@@ -12,6 +12,12 @@ export const sessions = $entity({
     refreshToken: t.uuid(),
     userId: db.ref(t.uuid(), () => users.cols.id),
     expiresAt: t.datetime(),
+    /**
+     * 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: t.optional(t.datetime()),
     ip: t.optional(t.text()),
     userAgent: t.optional(
       t.object({

package/src/api/users/jobs/UserJobs.ts

@@ -4,6 +4,7 @@ import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import { $repository } from "alepha/orm";
 import { sessions } from "../entities/sessions.ts";
+import { RealmProvider } from "../providers/RealmProvider.ts";
 
 /**
  * User-specific jobs wrapper service.
@@ -20,11 +21,19 @@ export class UserJobs {
   protected readonly log = $logger();
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly sessionRepository = $repository(sessions);
+  protected readonly realmProvider = $inject(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()`.
    */
   public readonly purgeExpiredSessions = $job({
     name: "api:users:purgeExpiredSessions",
@@ -34,28 +43,46 @@ export class UserJobs {
 
       this.log.info("Starting expired sessions purge", { cutoffTime: now });
 
-      const expiredSessions = await this.sessionRepository.findMany({
-        where: {
-          expiresAt: { lt: now },
-        },
+      const absoluteDeletedIds = await this.sessionRepository.deleteMany({
+        expiresAt: { lt: now },
       });
 
-      if (expiredSessions.length === 0) {
-        this.log.info("No expired sessions found");
-        return;
+      if (absoluteDeletedIds.length > 0) {
+        this.log.info("Expired sessions purged (absolute)", {
+          deletedCount: absoluteDeletedIds.length,
+        });
       }
 
-      this.log.info("Found expired sessions", {
-        count: expiredSessions.length,
-      });
+      // Idle sweep — only if the default realm has expirationIdle configured.
+      // Multi-realm setups with per-realm session tables should add their own
+      // job; this default job sweeps the default sessions table.
+      const realm = this.realmProvider.getRealm();
+      const settings = await realm.getSettings();
+      const idleMs = settings.refreshToken?.expirationIdle;
+      if (idleMs && idleMs > 0) {
+        const cutoff = this.dateTimeProvider
+          .now()
+          .subtract(idleMs, "milliseconds")
+          .toISOString();
 
-      const deletedIds = await this.sessionRepository.deleteMany({
-        expiresAt: { lt: now },
-      });
+        // Two passes: rows with an explicit lastUsedAt, and pre-migration rows
+        // where lastUsedAt is null — those fall back to createdAt.
+        const lastUsedDeletedIds = await this.sessionRepository.deleteMany({
+          lastUsedAt: { lt: cutoff },
+        });
+        const fallbackDeletedIds = await this.sessionRepository.deleteMany({
+          lastUsedAt: { isNull: true },
+          createdAt: { lt: cutoff },
+        });
 
-      this.log.info("Expired sessions purged successfully", {
-        deletedCount: deletedIds.length,
-      });
+        const idleTotal = lastUsedDeletedIds.length + fallbackDeletedIds.length;
+        if (idleTotal > 0) {
+          this.log.info("Expired sessions purged (idle)", {
+            deletedCount: idleTotal,
+            thresholdMs: idleMs,
+          });
+        }
+      }
     },
   });
 }

package/src/api/users/providers/RealmProvider.ts

@@ -71,6 +71,10 @@ export class RealmProvider {
           ...realmAuthSettingsAtom.options.default.loginRateLimit,
           ...realmOptions.settings?.loginRateLimit,
         },
+        refreshToken: {
+          ...realmAuthSettingsAtom.options.default.refreshToken,
+          ...realmOptions.settings?.refreshToken,
+        },
       },
       features,
       getSettings: async function () {

package/src/api/users/services/SessionService.ts

@@ -523,6 +523,7 @@ export class SessionService {
     const session = await this.sessions(userRealmName).create({
       userId: user.id,
       expiresAt,
+      lastUsedAt: this.dateTimeProvider.nowISOString(),
       ip: request?.ip,
       userAgent: request?.userAgent,
       refreshToken,
@@ -563,6 +564,27 @@ export class SessionService {
       throw new UnauthorizedError("Session expired");
     }
 
+    // Idle timeout check — opt-in via realm settings.
+    // Falls back to createdAt when lastUsedAt is null (pre-migration rows or
+    // sessions that never refreshed since the column was introduced).
+    const realm = this.realmProvider.getRealm(userRealmName);
+    const settings = await realm.getSettings();
+    const idleMs = settings.refreshToken?.expirationIdle;
+    if (idleMs && idleMs > 0) {
+      const lastUsedRef = session.lastUsedAt ?? session.createdAt;
+      const idleSince = now.diff(this.dateTimeProvider.of(lastUsedRef));
+      if (idleSince > idleMs) {
+        this.log.info("Session expired (idle timeout)", {
+          sessionId: session.id,
+          userId: session.userId,
+          idleMs: idleSince,
+          thresholdMs: idleMs,
+        });
+        await this.sessions(userRealmName).deleteById(session.id);
+        throw new UnauthorizedError("Session expired");
+      }
+    }
+
     const user = await this.users(userRealmName).getOne({
       where: {
         id: { eq: session.userId },
@@ -582,6 +604,11 @@ export class SessionService {
     // Auto-promote to admin if configured (handles "I promote you admin" case)
     await this.ensureAdminRole(user, userRealmName);
 
+    // Update lastUsedAt — sliding-window for idle timeout enforcement.
+    await this.sessions(userRealmName).updateById(session.id, {
+      lastUsedAt: now.toISOString(),
+    });
+
     this.log.debug("Session refreshed", {
       sessionId: session.id,
       userId: session.userId,

package/src/bucket/__tests__/NodeS3BucketProvider.spec.ts

@@ -0,0 +1,74 @@
+import { Alepha } from "alepha";
+import { describe, test } from "vitest";
+import {
+  AlephaBucket,
+  FileStorageProvider,
+  NodeS3BucketProvider,
+} from "../index.ts";
+import {
+  TestApp,
+  testCustomFileId,
+  testDeleteFile,
+  testDeleteNonExistentFile,
+  testDownloadAndMetadata,
+  testEmptyFiles,
+  testFileExistence,
+  testFileStream,
+  testNonExistentFile,
+  testNonExistentFileError,
+  testUploadAndExistence,
+  testUploadIntoBuckets,
+} from "./shared.ts";
+
+const alepha = Alepha.create()
+  .with({ provide: FileStorageProvider, use: NodeS3BucketProvider })
+  .with(AlephaBucket)
+  .with(TestApp);
+
+const provider = alepha.inject(NodeS3BucketProvider);
+
+describe("NodeS3BucketProvider", () => {
+  test("should upload a file and return a fileId", async () => {
+    await testUploadAndExistence(provider);
+  });
+
+  test("should download a file and restore its metadata", async () => {
+    await testDownloadAndMetadata(provider);
+  });
+
+  test("exists() should return false for a non-existent file", async () => {
+    await testNonExistentFile(provider);
+  });
+
+  test("exists() should return true for an existing file", async () => {
+    await testFileExistence(provider);
+  });
+
+  test("should delete a file", async () => {
+    await testDeleteFile(provider);
+  });
+
+  test("delete() should not throw for a non-existent file", async () => {
+    await testDeleteNonExistentFile(provider);
+  });
+
+  test("download() should throw FileNotFoundError for a non-existent file", async () => {
+    await testNonExistentFileError(provider);
+  });
+
+  test("should handle uploading to different buckets", async () => {
+    await testUploadIntoBuckets(provider);
+  });
+
+  test("should handle empty files correctly", async () => {
+    await testEmptyFiles(provider);
+  });
+
+  test("should be able to upload with a specific fileId", async () => {
+    await testCustomFileId(provider);
+  });
+
+  test("should be able to upload, stream with metadata", async () => {
+    await testFileStream(provider);
+  });
+});

package/src/bucket/index.ts

@@ -7,6 +7,7 @@ import {
 import { FileStorageProvider } from "./providers/FileStorageProvider.ts";
 import { LocalFileStorageProvider } from "./providers/LocalFileStorageProvider.ts";
 import { MemoryFileStorageProvider } from "./providers/MemoryFileStorageProvider.ts";
+import { NodeS3BucketProvider } from "./providers/NodeS3BucketProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -16,6 +17,7 @@ export * from "./providers/CloudflareR2Provider.ts";
 export * from "./providers/FileStorageProvider.ts";
 export * from "./providers/LocalFileStorageProvider.ts";
 export * from "./providers/MemoryFileStorageProvider.ts";
+export * from "./providers/NodeS3BucketProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -38,6 +40,14 @@ declare module "alepha" {
       id: string;
       bucket: BucketPrimitive;
     };
+    /**
+     * Triggered when a file is downloaded from a bucket.
+     */
+    "bucket:file:downloaded": {
+      id: string;
+      file: FileLike;
+      bucket: BucketPrimitive;
+    };
   }
 }
 
@@ -61,15 +71,22 @@ export const AlephaBucket = $module({
   name: "alepha.bucket",
   primitives: [$bucket],
   services: [FileStorageProvider],
-  variants: [MemoryFileStorageProvider, LocalFileStorageProvider],
+  variants: [
+    MemoryFileStorageProvider,
+    LocalFileStorageProvider,
+    NodeS3BucketProvider,
+  ],
   register: (alepha) => {
+    const useS3 = !!alepha.env.S3_ENDPOINT;
     alepha.with({
       optional: true,
       provide: FileStorageProvider,
       use:
         alepha.isTest() || alepha.isServerless()
           ? MemoryFileStorageProvider
-          : LocalFileStorageProvider,
+          : useS3
+            ? NodeS3BucketProvider
+            : LocalFileStorageProvider,
     });
   },
 });

package/src/bucket/primitives/$bucket.ts

@@ -288,7 +288,15 @@ export class BucketPrimitive extends Primitive<BucketPrimitiveOptions> {
    * Downloads a file from the bucket.
    */
   public async download(fileId: string): Promise<FileLike> {
-    return this.provider.download(this.name, fileId);
+    const file = await this.provider.download(this.name, fileId);
+
+    await this.alepha.events.emit("bucket:file:downloaded", {
+      id: fileId,
+      bucket: this,
+      file,
+    });
+
+    return file;
   }
 
   protected $provider() {