alepha 0.14.3 → 0.15.0

package/src/security/primitives/$role.ts

@@ -1,7 +1,7 @@
 import { $inject, createPrimitive, KIND, Primitive } from "alepha";
 import { SecurityProvider } from "../providers/SecurityProvider.ts";
+import type { IssuerPrimitive } from "./$issuer.ts";
 import type { PermissionPrimitive } from "./$permission.ts";
-import type { RealmPrimitive } from "./$realm.ts";
 
 /**
  * Create a new role.
@@ -23,7 +23,7 @@ export interface RolePrimitiveOptions {
    */
   description?: string;
 
-  realm?: string | RealmPrimitive;
+  issuer?: string | IssuerPrimitive;
 
   permissions?: Array<
     | string
@@ -60,10 +60,10 @@ export class RolePrimitive extends Primitive<RolePrimitiveOptions> {
   }
 
   /**
-   * Get the realm of the role.
+   * Get the issuer of the role.
    */
-  public get realm(): string | RealmPrimitive | undefined {
-    return this.options.realm;
+  public get issuer(): string | IssuerPrimitive | undefined {
+    return this.options.issuer;
   }
 
   public can(permission: string | PermissionPrimitive): boolean {

package/src/security/primitives/$serviceAccount.spec.ts

@@ -1,7 +1,7 @@
 import { Alepha } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { describe, expect, it } from "vitest";
-import { $realm, $serviceAccount } from "../index.ts";
+import { $issuer, $serviceAccount } from "../index.ts";
 
 class App {
   oauth2 = $serviceAccount({
@@ -16,12 +16,12 @@ class App {
     expiresIn: 300, // 5 minutes
   };
 
-  realm = $realm({
-    secret: "your-realm-secret",
+  issuer = $issuer({
+    secret: "your-issuer-secret",
   });
 
   jwt = $serviceAccount({
-    realm: this.realm,
+    issuer: this.issuer,
     user: {
       id: "service-account",
     },
@@ -42,7 +42,7 @@ describe("$serviceAccount", () => {
     );
     expect(payload).toEqual({
       sub: expect.any(String),
-      aud: "realm",
+      aud: "issuer",
       iat: expect.any(Number),
       exp: expect.any(Number),
       sid: expect.any(String),

package/src/security/primitives/$serviceAccount.ts

@@ -1,7 +1,7 @@
 import { $context } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
-import type { AccessTokenResponse, RealmPrimitive } from "./$realm.ts";
+import type { AccessTokenResponse, IssuerPrimitive } from "./$issuer.ts";
 
 /**
  * Allow to get an access token for a service account.
@@ -138,7 +138,7 @@ export const $serviceAccount = (
         return tokenFromCache;
       }
 
-      const token = await options.realm.createToken(options.user);
+      const token = await options.issuer.createToken(options.user);
 
       cacheToken({
         ...token,
@@ -157,7 +157,7 @@ export type ServiceAccountPrimitiveOptions = {
       oauth2: Oauth2ServiceAccountPrimitiveOptions;
     }
   | {
-      realm: RealmPrimitive;
+      issuer: IssuerPrimitive;
       user: UserAccount;
     }
 );

package/src/{server/security → security}/providers/ServerSecurityProvider.ts

@@ -1,19 +1,17 @@
 import { randomUUID } from "node:crypto";
 import { $hook, $inject, Alepha } from "alepha";
 import { $logger } from "alepha/logger";
-import {
-  JwtProvider,
-  type Permission,
-  SecurityProvider,
-  type UserAccountToken,
-  userAccountInfoSchema,
-} from "alepha/security";
 import {
   $action,
   ForbiddenError,
   type ServerRequest,
   UnauthorizedError,
 } from "alepha/server";
+import type { UserAccountToken } from "../interfaces/UserAccountToken.ts";
+import type { Permission } from "../schemas/permissionSchema.ts";
+import { userAccountInfoSchema } from "../schemas/userAccountInfoSchema.ts";
+import { JwtProvider } from "./JwtProvider.ts";
+import { SecurityProvider } from "./SecurityProvider.ts";
 import {
   type BasicAuthOptions,
   isBasicAuth,

package/src/server/auth/primitives/$auth.ts

@@ -9,7 +9,7 @@ import {
 import { DateTimeProvider } from "alepha/datetime";
 import {
   type AccessTokenResponse,
-  type RealmPrimitive,
+  type IssuerPrimitive,
   SecurityError,
   SecurityProvider,
   type UserAccount,
@@ -105,10 +105,10 @@ export type AuthExternal = {
  * When using your own authentication system, e.g. using a database to store user accounts.
  * This is usually used with a custom login form.
  *
- * This relies on the `realm`, which is used to create/verify the access token.
+ * This relies on the `issuer`, which is used to create/verify the access token.
  */
 export type AuthInternal = {
-  realm: RealmPrimitive;
+  issuer: IssuerPrimitive;
 } & (
   | {
       /**
@@ -261,9 +261,9 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
     return this.options.name ?? this.config.propertyKey;
   }
 
-  public get realm(): RealmPrimitive | undefined {
-    if ("realm" in this.options) {
-      return this.options.realm;
+  public get issuer(): IssuerPrimitive | undefined {
+    if ("issuer" in this.options) {
+      return this.options.issuer;
     }
     return undefined;
   }
@@ -308,13 +308,13 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
     refreshToken: string,
     accessToken?: string,
   ): Promise<AccessTokenResponse> {
-    if ("realm" in this.options) {
-      return this.options.realm
+    if ("issuer" in this.options) {
+      return this.options.issuer
         .refreshToken(refreshToken, accessToken)
         .then((it) => it.tokens)
         .catch((error) => {
           throw new SecurityError(
-            "Failed to refresh access token using the refresh token (realm)",
+            "Failed to refresh access token using the refresh token (issuer)",
             {
               cause: error,
             },
@@ -337,7 +337,7 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
     }
 
     throw new AlephaError(
-      "No realm or OAuth2 configuration available for refreshing the access token",
+      "No issuer or OAuth2 configuration available for refreshing the access token",
     );
   }
 

package/src/server/auth/primitives/$authCredentials.ts

@@ -1,5 +1,5 @@
 import { AlephaError } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import {
   $auth,
   type CredentialsFn,
@@ -13,7 +13,7 @@ import {
  * Uses username and password to authenticate users.
  */
 export const $authCredentials = (
-  realm: RealmPrimitive & WithLoginFn,
+  realm: IssuerPrimitive & WithLoginFn,
   options: Partial<CredentialsOptions> = {},
 ) => {
   const name = "credentials";
@@ -29,7 +29,7 @@ export const $authCredentials = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     credentials: {
       account,

package/src/server/auth/primitives/$authGithub.ts

@@ -1,5 +1,5 @@
 import { $context, AlephaError, t } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import type { OAuth2Profile } from "../providers/ServerAuthProvider.ts";
 import {
   $auth,
@@ -19,7 +19,7 @@ import {
  * - `GITHUB_CLIENT_SECRET`: The client secret obtained from the GitHub Developer Settings.
  */
 export const $authGithub = (
-  realm: RealmPrimitive & WithLinkFn,
+  realm: IssuerPrimitive & WithLinkFn,
   options: Partial<OidcOptions> = {},
 ) => {
   const { alepha } = $context();
@@ -45,7 +45,7 @@ export const $authGithub = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     oauth: {
       clientId: env.GITHUB_CLIENT_ID!,

package/src/server/auth/primitives/$authGoogle.ts

@@ -1,5 +1,5 @@
 import { $context, AlephaError, t } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import {
   $auth,
   type LinkAccountFn,
@@ -18,7 +18,7 @@ import {
  * - `GOOGLE_CLIENT_SECRET`: The client secret obtained from the Google Developer Console.
  */
 export const $authGoogle = (
-  realm: RealmPrimitive & WithLinkFn,
+  realm: IssuerPrimitive & WithLinkFn,
   options: Partial<OidcOptions> = {},
 ) => {
   const { alepha } = $context();
@@ -44,7 +44,7 @@ export const $authGoogle = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     oidc: {
       issuer: "https://accounts.google.com",

package/src/server/auth/providers/ServerAuthProvider.ts

@@ -71,8 +71,8 @@ export class ServerAuthProvider {
 
     for (const identity of this.identities) {
       if (filters.realmName) {
-        const realm = "realm" in identity.options && identity.options.realm;
-        if (!realm || realm.name !== filters.realmName) {
+        const issuer = identity.issuer;
+        if (!issuer || issuer.name !== filters.realmName) {
           continue;
         }
       }
@@ -145,7 +145,7 @@ export class ServerAuthProvider {
       // [feature] support for auth providers with fallback
       if (!request.headers.authorization) {
         for (const provider of this.identities) {
-          if (!("realm" in provider.options) && !!provider.options.fallback) {
+          if ("fallback" in provider.options && !!provider.options.fallback) {
             const token = await provider.options.fallback();
             if (token) {
               request.headers.authorization = `Bearer ${token}`;
@@ -340,8 +340,8 @@ export class ServerAuthProvider {
         realm: query.realm,
       });
 
-      const realm = "realm" in provider.options && provider.options.realm;
-      if (!realm) {
+      const issuer = provider.issuer;
+      if (!issuer) {
         throw new SecurityError(
           `Auth provider '${query.provider}' does not support password grant`,
         );
@@ -373,7 +373,7 @@ export class ServerAuthProvider {
 
       const tokens = {
         provider: query.provider,
-        ...(await realm.createToken(user)),
+        ...(await issuer.createToken(user)),
       };
 
       // for web applications, we store tokens in cookies
@@ -519,10 +519,10 @@ export class ServerAuthProvider {
 
       this.authorizationCode.del({ cookies });
 
-      const realm = "realm" in provider.options && provider.options.realm;
+      const issuer = provider.issuer;
 
       // external, full OIDC System (e.g. Keycloak, Auth0)
-      if (!realm) {
+      if (!issuer) {
         this.setTokens(externalTokens, cookies);
         reply.redirect(redirectUri);
         return;
@@ -531,7 +531,7 @@ export class ServerAuthProvider {
       // internal, we need to create our own tokens
 
       const user = await provider.user(externalTokens);
-      const tokens = await realm.createToken(user);
+      const tokens = await issuer.createToken(user);
 
       this.setTokens(
         {
@@ -570,9 +570,9 @@ export class ServerAuthProvider {
       this.tokens.del({ cookies });
 
       // for internal providers, we can delete the session - if available
-      if ("realm" in provider.options && tokens.refresh_token) {
+      if (provider.issuer && tokens.refresh_token) {
         const onDeleteSession =
-          provider.options.realm.options.settings?.onDeleteSession;
+          provider.issuer.options.settings?.onDeleteSession;
         if (onDeleteSession) {
           try {
             await onDeleteSession(tokens.refresh_token);
@@ -635,8 +635,8 @@ export class ServerAuthProvider {
         return false;
       }
 
-      // If realm filter is specified, match against provider's realm
-      if (realmName && identity.realm?.name !== realmName) {
+      // If realm filter is specified, match against provider's issuer
+      if (realmName && identity.issuer?.name !== realmName) {
         return false;
       }
 

package/src/server/cache/providers/ServerCacheProvider.spec.ts

@@ -865,6 +865,189 @@ describe("ServerCacheProvider", () => {
     });
   });
 
+  describe("Stream caching support", () => {
+    test("should cache ReadableStream responses via tee", async ({
+      expect,
+    }) => {
+      // Create a simple ReadableStream that emits chunks
+      const chunks = ["Hello", " ", "World"];
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const encoder = new TextEncoder();
+          for (const chunk of chunks) {
+            controller.enqueue(encoder.encode(chunk));
+          }
+          controller.close();
+        },
+      });
+
+      // Access the protected method via type assertion
+      const provider = cacheProvider as any;
+      const key = "test-stream-key";
+
+      // Collect the stream for cache
+      const hash = await provider.collectStreamForCache(
+        stream,
+        key,
+        200,
+        "text/html",
+        true,
+      );
+
+      expect(hash).toBeDefined();
+      expect(hash).toMatch(/^"[a-f0-9]+"$/); // ETag format
+
+      // Verify the cache contains the collected content
+      const cached = await provider.cache.get(key);
+      expect(cached).toBeDefined();
+      expect(cached.body).toBe("Hello World");
+      expect(cached.status).toBe(200);
+      expect(cached.contentType).toBe("text/html");
+    });
+
+    test("should tee stream so client and cache both receive data", async ({
+      expect,
+    }) => {
+      const encoder = new TextEncoder();
+      const chunks = ["<html>", "<body>", "Content", "</body>", "</html>"];
+
+      const originalStream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          for (const chunk of chunks) {
+            controller.enqueue(encoder.encode(chunk));
+          }
+          controller.close();
+        },
+      });
+
+      // Tee the stream like ServerCacheProvider does
+      const [clientStream, cacheStream] = originalStream.tee();
+
+      // Read from client stream (simulates client receiving data)
+      const clientReader = clientStream.getReader();
+      const clientChunks: string[] = [];
+      const decoder = new TextDecoder();
+
+      while (true) {
+        const { done, value } = await clientReader.read();
+        if (done) break;
+        clientChunks.push(decoder.decode(value, { stream: true }));
+      }
+      clientChunks.push(decoder.decode()); // flush
+
+      // Read from cache stream (simulates cache collection)
+      const cacheReader = cacheStream.getReader();
+      const cacheChunks: string[] = [];
+      const cacheDecoder = new TextDecoder();
+
+      while (true) {
+        const { done, value } = await cacheReader.read();
+        if (done) break;
+        cacheChunks.push(cacheDecoder.decode(value, { stream: true }));
+      }
+      cacheChunks.push(cacheDecoder.decode()); // flush
+
+      // Both should receive the same data
+      const clientData = clientChunks.join("");
+      const cacheData = cacheChunks.join("");
+
+      expect(clientData).toBe("<html><body>Content</body></html>");
+      expect(cacheData).toBe("<html><body>Content</body></html>");
+      expect(clientData).toBe(cacheData);
+    });
+
+    test("should handle empty stream gracefully", async ({ expect }) => {
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.close();
+        },
+      });
+
+      const provider = cacheProvider as any;
+      const key = "empty-stream-key";
+
+      const hash = await provider.collectStreamForCache(
+        stream,
+        key,
+        200,
+        "text/html",
+        true,
+      );
+
+      expect(hash).toBeDefined();
+
+      const cached = await provider.cache.get(key);
+      expect(cached).toBeDefined();
+      expect(cached.body).toBe("");
+    });
+
+    test("should handle large stream with multiple chunks", async ({
+      expect,
+    }) => {
+      const encoder = new TextEncoder();
+      const chunkCount = 100;
+      const chunkContent = "x".repeat(1000);
+
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          for (let i = 0; i < chunkCount; i++) {
+            controller.enqueue(encoder.encode(chunkContent));
+          }
+          controller.close();
+        },
+      });
+
+      const provider = cacheProvider as any;
+      const key = "large-stream-key";
+
+      const hash = await provider.collectStreamForCache(
+        stream,
+        key,
+        200,
+        "text/html",
+        false,
+      );
+
+      // hash should be undefined when generateEtag is false
+      expect(hash).toBeUndefined();
+
+      const cached = await provider.cache.get(key);
+      expect(cached).toBeDefined();
+      expect(cached.body.length).toBe(chunkCount * chunkContent.length);
+    });
+
+    test("should generate correct ETag for streamed content", async ({
+      expect,
+    }) => {
+      const content = "Test content for ETag";
+      const encoder = new TextEncoder();
+
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(encoder.encode(content));
+          controller.close();
+        },
+      });
+
+      const provider = cacheProvider as any;
+
+      // Generate ETag from stream
+      const streamHash = await provider.collectStreamForCache(
+        stream,
+        "etag-test-key",
+        200,
+        "text/html",
+        true,
+      );
+
+      // Generate ETag from string directly
+      const stringHash = cacheProvider.generateETag(content);
+
+      // Both should produce the same ETag
+      expect(streamHash).toBe(stringHash);
+    });
+  });
+
   describe("Error response caching", () => {
     test("should NOT cache 500 error responses", async ({ expect }) => {
       const response1 = await app.errorAction.fetch();

package/src/server/cache/providers/ServerCacheProvider.ts

@@ -204,7 +204,7 @@ export class ServerCacheProvider {
 
   protected readonly onSend = $hook({
     on: "server:onSend",
-    handler: async ({ route, request }) => {
+    handler: ({ route, request }) => {
       // before sending the response, check if the ETag matches
       // and if so, return a 304 Not Modified response
       // -> this is only relevant for etag-only routes, not cached routes <-
@@ -261,24 +261,55 @@ export class ServerCacheProvider {
         return;
       }
 
-      // Only process string responses (text, html, json, etc.)
-      // Buffer is not supported by alepha/cache for now
-      if (typeof response.body !== "string") {
-        return;
-      }
-
       // Don't cache error responses (status >= 400)
       if (response.status && response.status >= 400) {
         return;
       }
 
+      // Initialize headers if not present
+      response.headers ??= {};
+
       const key = this.createCacheKey(route, request);
+
+      // Handle ReadableStream responses (e.g., SSR streaming)
+      if (response.body instanceof ReadableStream && shouldStore) {
+        // Tee the stream: one for client, one for cache collection
+        const [clientStream, cacheStream] = (
+          response.body as ReadableStream<Uint8Array>
+        ).tee();
+
+        // Replace response body with client stream (continues streaming to client)
+        response.body = clientStream as typeof response.body;
+
+        // Collect cache stream in background (non-blocking)
+        this.collectStreamForCache(
+          cacheStream,
+          key,
+          response.status,
+          response.headers?.["content-type"],
+          shouldUseEtag,
+        )
+          .then((hash) => {
+            if (shouldUseEtag && hash) {
+              // Note: headers already sent for streaming, etag only useful for future requests
+              this.log.trace("Stream cached with hash", { key, hash });
+            }
+          })
+          .catch((err) => {
+            this.log.warn("Failed to cache stream", { key, error: err });
+          });
+
+        return;
+      }
+
+      // Only process string responses (text, html, json, etc.)
+      if (typeof response.body !== "string") {
+        return;
+      }
+
       const generatedEtag = this.generateETag(response.body);
       const lastModified = this.time.toISOString();
 
-      // Initialize headers if not present
-      response.headers ??= {};
-
       // Store response if storing is enabled
       if (shouldStore) {
         this.log.trace("Storing response", {
@@ -404,6 +435,60 @@ export class ServerCacheProvider {
 
     return `${route.method}:${route.path.replaceAll(":", "")}:${params.join(",").replaceAll(":", "")}`;
   }
+
+  /**
+   * Collect a ReadableStream into a string and store it in the cache.
+   * This runs in the background while the original stream is sent to the client.
+   *
+   * @param stream - The stream to collect
+   * @param key - Cache key
+   * @param status - HTTP status code
+   * @param contentType - Content-Type header
+   * @param generateEtag - Whether to generate and return an ETag
+   * @returns The generated ETag hash, or undefined
+   */
+  protected async collectStreamForCache(
+    stream: ReadableStream<Uint8Array>,
+    key: string,
+    status: number | undefined,
+    contentType: string | undefined,
+    generateEtag: boolean,
+  ): Promise<string | undefined> {
+    const chunks: Uint8Array[] = [];
+    const reader = stream.getReader();
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+
+      // Combine chunks into a single string
+      const decoder = new TextDecoder();
+      const body =
+        chunks
+          .map((chunk) => decoder.decode(chunk, { stream: true }))
+          .join("") + decoder.decode(); // Flush remaining
+
+      const hash = this.generateETag(body);
+      const lastModified = this.time.toISOString();
+
+      this.log.trace("Storing streamed response", { key });
+
+      await this.cache.set(key, {
+        body,
+        status,
+        contentType,
+        lastModified,
+        hash,
+      });
+
+      return generateEtag ? hash : undefined;
+    } finally {
+      reader.releaseLock();
+    }
+  }
 }
 
 export type ServerRouteCache =