alepha 0.20.3 → 0.20.5

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() {

package/src/bucket/providers/CloudflareR2Provider.ts

@@ -1,3 +1,4 @@
+import type { R2Bucket } from "@cloudflare/workers-types";
 import {
   $env,
   $hook,
@@ -14,142 +15,6 @@ import type { FileStorageProvider } from "./FileStorageProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-/**
- * R2Bucket interface matching Cloudflare's R2 API.
- */
-export interface R2Bucket {
-  put(
-    key: string,
-    value:
-      | ReadableStream
-      | ArrayBuffer
-      | ArrayBufferView
-      | string
-      | Blob
-      | null,
-    options?: R2PutOptions,
-  ): Promise<R2Object | null>;
-  get(key: string, options?: R2GetOptions): Promise<R2ObjectBody | null>;
-  head(key: string): Promise<R2Object | null>;
-  delete(keys: string | string[]): Promise<void>;
-  list(options?: R2ListOptions): Promise<R2Objects>;
-  createMultipartUpload(
-    key: string,
-    options?: R2MultipartOptions,
-  ): Promise<R2MultipartUpload>;
-}
-
-export interface R2Object {
-  key: string;
-  version: string;
-  size: number;
-  etag: string;
-  httpEtag: string;
-  checksums: R2Checksums;
-  uploaded: Date;
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  range?: R2Range;
-  storageClass: string;
-}
-
-export interface R2ObjectBody extends R2Object {
-  body: ReadableStream;
-  bodyUsed: boolean;
-  arrayBuffer(): Promise<ArrayBuffer>;
-  text(): Promise<string>;
-  json<T>(): Promise<T>;
-  blob(): Promise<Blob>;
-}
-
-export interface R2PutOptions {
-  onlyIf?: R2Conditional;
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  md5?: ArrayBuffer | string;
-  sha1?: ArrayBuffer | string;
-  sha256?: ArrayBuffer | string;
-  sha384?: ArrayBuffer | string;
-  sha512?: ArrayBuffer | string;
-  storageClass?: string;
-}
-
-export interface R2GetOptions {
-  onlyIf?: R2Conditional;
-  range?: R2Range;
-}
-
-export interface R2ListOptions {
-  limit?: number;
-  prefix?: string;
-  cursor?: string;
-  delimiter?: string;
-  startAfter?: string;
-  include?: ("httpMetadata" | "customMetadata")[];
-}
-
-export interface R2Objects {
-  objects: R2Object[];
-  truncated: boolean;
-  cursor?: string;
-  delimitedPrefixes: string[];
-}
-
-export interface R2Checksums {
-  md5?: ArrayBuffer;
-  sha1?: ArrayBuffer;
-  sha256?: ArrayBuffer;
-  sha384?: ArrayBuffer;
-  sha512?: ArrayBuffer;
-}
-
-export interface R2HTTPMetadata {
-  contentType?: string;
-  contentLanguage?: string;
-  contentDisposition?: string;
-  contentEncoding?: string;
-  cacheControl?: string;
-  cacheExpiry?: Date;
-}
-
-export interface R2Conditional {
-  etagMatches?: string;
-  etagDoesNotMatch?: string;
-  uploadedBefore?: Date;
-  uploadedAfter?: Date;
-  secondsGranularity?: boolean;
-}
-
-export interface R2Range {
-  offset?: number;
-  length?: number;
-  suffix?: number;
-}
-
-export interface R2MultipartOptions {
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  storageClass?: string;
-}
-
-export interface R2MultipartUpload {
-  key: string;
-  uploadId: string;
-  uploadPart(
-    partNumber: number,
-    value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob,
-  ): Promise<R2UploadedPart>;
-  abort(): Promise<void>;
-  complete(uploadedParts: R2UploadedPart[]): Promise<R2Object>;
-}
-
-export interface R2UploadedPart {
-  partNumber: number;
-  etag: string;
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
 /**
  * Cloudflare R2 storage provider.
  *
@@ -311,7 +176,7 @@ export class CloudflareR2Provider implements FileStorageProvider {
       type: contentType,
       size: object.size,
       lastModified: object.uploaded.getTime(),
-      stream: () => object.body,
+      stream: () => object.body as unknown as ReadableStream,
       arrayBuffer: () => object.arrayBuffer(),
       text: () => object.text(),
     };