alepha 0.7.7 → 0.8.1

package/server/cache.d.ts

@@ -1,8 +1,8 @@
-import { Cache, CacheDescriptorOptions, CacheDescriptorProvider } from "@alepha/cache";
-import { ServerHandler, ServerRequestConfig } from "@alepha/server";
-import * as _alepha_core1 from "@alepha/core";
-import { Alepha, Module, OPTIONS } from "@alepha/core";
-import { DateTimeProvider, DurationLike } from "@alepha/datetime";
+import { Cache, CacheDescriptorOptions, CacheDescriptorProvider } from "alepha/cache";
+import { ServerHandler, ServerRequestConfig } from "alepha/server";
+import * as _alepha_core1 from "alepha";
+import { Alepha, Module, OPTIONS } from "alepha";
+import { DateTimeProvider, DurationLike } from "alepha/datetime";
 
 //#region src/providers/ServerCacheProvider.d.ts
 declare module "alepha/server" {
@@ -46,9 +46,6 @@ type RouteLike = {
 //#endregion
 //#region src/index.d.ts
 /**
- * # Alepha Server Cache Module
- *
- * @description
  * Plugin for Alepha Server that provides server-side caching capabilities.
  * It uses the Alepha Cache module to cache responses from server actions ($action).
  * It also provides a ETag-based cache invalidation mechanism.
@@ -80,6 +77,8 @@ declare class AlephaServerCache implements Module {
   readonly name = "alepha.server.cache";
   readonly $services: (alepha: Alepha) => Alepha;
 }
+//# sourceMappingURL=index.d.ts.map
+
 //#endregion
 export { AlephaServerCache, ServerCacheProvider, ServerRouteCache };
 //# sourceMappingURL=index.d.ts.map

package/server/compress.cjs

@@ -0,0 +1,8 @@
+'use strict';
+var m = require('@alepha/server-compress');
+Object.keys(m).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return m[k]; }
+	});
+});

package/server/compress.d.ts

@@ -0,0 +1,26 @@
+import { ServerResponse } from "alepha/server";
+import { Transform } from "node:stream";
+import { Alepha, HookDescriptor, Module } from "alepha";
+
+//#region src/providers/ServerCompressProvider.d.ts
+declare class ServerCompressProvider {
+  compressors: Record<string, {
+    compress: (...args: any[]) => Promise<Buffer>;
+    stream: (options?: any) => Transform;
+  } | undefined>;
+  readonly onResponse: HookDescriptor<"server:onResponse">;
+  protected isAllowedContentType(contentType: string | undefined): boolean;
+  protected compress(encoding: keyof typeof (void 0).compressors, response: ServerResponse): Promise<void>;
+  protected getParams(encoding: keyof typeof (void 0).compressors): Record<number, any>;
+  protected setHeaders(response: ServerResponse, encoding: keyof typeof (void 0).compressors): void;
+}
+//#endregion
+//#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
+declare class AlephaServerCompress implements Module {
+  readonly name = "alepha.server.compress";
+  readonly $services: (alepha: Alepha) => void;
+}
+//#endregion
+export { AlephaServerCompress, ServerCompressProvider };
+//# sourceMappingURL=index.d.ts.map

package/server/compress.js

@@ -0,0 +1 @@
+export * from '@alepha/server-compress'

package/server/cookies.d.ts

@@ -1,32 +1,59 @@
-import * as _alepha_core1 from "@alepha/core";
-import { KIND, OPTIONS, Static, TSchema } from "@alepha/core";
-import { DurationLike } from "@alepha/datetime";
+import { Alepha, HookDescriptor, KIND, Logger, Module, OPTIONS, Static, TObject, TOptional, TSchema, TString } from "alepha";
+import { DateTimeProvider, DurationLike } from "alepha/datetime";
 
 //#region src/descriptors/$cookie.d.ts
+declare const KEY = "COOKIE";
+/**
+* Declares a type-safe, configurable HTTP cookie.
+* This descriptor provides methods to get, set, and delete the cookie
+* within the server request/response cycle.
+*/
+declare const $cookie: {
+  <T extends TSchema>(options: CookieDescriptorOptions<T>): CookieDescriptor<T>;
+  [KIND]: string;
+};
+// ---------------------------------------------------------------------------------------------------------------------
 interface CookieDescriptorOptions<T extends TSchema> {
+  /** The schema for the cookie's value, used for validation and type safety. */
   schema: T;
-  name: string;
+  /** The name of the cookie. */
+  name?: string;
+  /** The cookie's path. Defaults to "/". */
   path?: string;
+  /** Time-to-live for the cookie. Maps to `Max-Age`. */
   ttl?: DurationLike;
+  /** If true, the cookie is only sent over HTTPS. Defaults to true in production. */
   secure?: boolean;
+  /** If true, the cookie cannot be accessed by client-side scripts. */
   httpOnly?: boolean;
+  /** SameSite policy for the cookie. Defaults to "lax". */
   sameSite?: "strict" | "lax" | "none";
+  /** The domain for the cookie. */
   domain?: string;
+  /** If true, the cookie value will be compressed using zlib. */
   compress?: boolean;
+  /** If true, the cookie value will be encrypted. Requires `COOKIE_SECRET` env var. */
   encrypt?: boolean;
+  /** If true, the cookie will be signed to prevent tampering. Requires `COOKIE_SECRET` env var. */
   sign?: boolean;
 }
 interface CookieDescriptor<T extends TSchema> {
-  [KIND]: "COOKIE";
+  [KIND]: typeof KEY;
   [OPTIONS]: CookieDescriptorOptions<T>;
-  set: (cookies: Cookies, value: Static<T>) => void;
-  get: (cookies: Cookies) => Static<T> | undefined;
-  del: (cookies: Cookies) => void;
+  schema: T;
+  /** Sets the cookie with the given value in the current request's response. */
+  set: (value: Static<T>, options?: {
+    cookies?: Cookies;
+  }) => void;
+  /** Gets the cookie value from the current request. Returns undefined if not found or invalid. */
+  get: (options?: {
+    cookies?: Cookies;
+  }) => Static<T> | undefined;
+  /** Deletes the cookie in the current request's response. */
+  del: (options?: {
+    cookies?: Cookies;
+  }) => void;
 }
-declare const $cookie: {
-  <T extends TSchema>(options: CookieDescriptorOptions<T>): CookieDescriptor<T>;
-  [KIND]: string;
-};
 interface Cookies {
   req: Record<string, string>;
   res: Record<string, Cookie | null>;
@@ -42,22 +69,226 @@ interface Cookie {
 }
 //#endregion
 //#region src/providers/ServerCookiesProvider.d.ts
+declare const envSchema: TObject<{
+  COOKIE_SECRET: TOptional<TString>;
+}>;
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+}
 declare class ServerCookiesProvider {
-  readonly onRequest: _alepha_core1.HookDescriptor<"server:onRequest">;
-  readonly onSend: _alepha_core1.HookDescriptor<"server:onSend">;
-  fromHeader(header: string): Record<string, string>;
-  toHeader(cookies: Record<string, Cookie | null>, isHttps?: boolean): string[];
+  protected readonly alepha: Alepha;
+  protected readonly log: Logger;
+  protected readonly env: Static<typeof envSchema>;
+  protected readonly dateTimeProvider: DateTimeProvider;
+  // Crypto constants
+  protected readonly ALGORITHM = "aes-256-gcm";
+  protected readonly IV_LENGTH = 16;
+  protected readonly AUTH_TAG_LENGTH = 16;
+  protected readonly SIGNATURE_LENGTH = 32;
+  protected readonly configure: HookDescriptor<"configure">;
+  protected createApi<T extends TSchema>(name: string, options: CookieDescriptorOptions<T>): CookieDescriptor<T>;
+  readonly onRequest: HookDescriptor<"server:onRequest">;
+  readonly onSend: HookDescriptor<"server:onSend">;
+  protected getCookiesFromContext(cookies?: Cookies): Cookies;
+  protected getCookie<T extends TSchema>(name: string, options: CookieDescriptorOptions<T>, contextCookies?: Cookies): Static<T> | undefined;
+  protected setCookie<T extends TSchema>(name: string, options: CookieDescriptorOptions<T>, data: Static<T>, contextCookies?: Cookies): void;
+  protected deleteCookie<T extends TSchema>(name: string, contextCookies?: Cookies): void;
+  // --- Crypto & Parsing ---
+  protected encrypt(text: string): string;
+  protected decrypt(encryptedText: string): string;
+  secretKey(): string;
+  protected sign(data: string): string;
+  protected parseRequestCookies(header: string): Record<string, string>;
+  protected serializeResponseCookies(cookies: Record<string, Cookie | null>, isHttps: boolean): string[];
 }
 //#endregion
 //#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
 declare module "alepha/server" {
   interface ServerRequest {
     cookies: Cookies;
   }
 }
-declare class AlephaServerCookies {
+/**
+* Provides HTTP cookie management capabilities for server requests and responses with type-safe cookie descriptors.
+*
+* The server-cookies module enables declarative cookie handling using the `$cookie` descriptor on class properties.
+* It offers automatic cookie parsing, secure cookie configuration, and seamless integration with server routes
+* for managing user sessions, preferences, and authentication tokens.
+*
+* **Key Features:**
+* - Declarative cookie definition with `$cookie` descriptor
+* - Automatic cookie parsing from requests
+* - Secure cookie configuration (httpOnly, secure, sameSite)
+* - Type-safe cookie values with schema validation
+* - Automatic cookie serialization and deserialization
+* - Integration with server request/response lifecycle
+*
+* **Basic Usage:**
+* ```ts
+* import { Alepha, run, t } from "alepha";
+* import { AlephaServer, $route } from "alepha/server";
+* import { AlephaServerCookies, $cookie } from "alepha/server/cookies";
+*
+* class AuthRoutes {
+*   // Define authentication cookie
+*   authToken = $cookie({
+*     name: "auth_token",
+*     httpOnly: true,
+*     secure: true,
+*     sameSite: "strict",
+*     maxAge: "7d",
+*   });
+*
+*   // Define user preferences cookie
+*   userPrefs = $cookie({
+*     name: "user_prefs",
+*     schema: t.object({
+*       theme: t.union([t.literal("light"), t.literal("dark")]),
+*       language: t.string(),
+*     }),
+*     maxAge: "30d",
+*   });
+*
+*   login = $route({
+*     path: "/login",
+*     method: "POST",
+*     schema: {
+*       body: t.object({
+*         email: t.string(),
+*         password: t.string(),
+*       }),
+*     },
+*     handler: async ({ body, reply }) => {
+*       const user = await authenticateUser(body.email, body.password);
+*       if (!user) {
+*         return new Response("Invalid credentials", { status: 401 });
+*       }
+*
+*       const token = await generateJWT(user.id);
+*
+*       // Set authentication cookie
+*       this.authToken.set(reply, token);
+*
+*       return Response.json({ success: true, user });
+*     },
+*   });
+*
+*   profile = $route({
+*     path: "/profile",
+*     method: "GET",
+*     handler: async ({ cookies }) => {
+*       // Get authentication token from cookie
+*       const token = this.authToken.get(cookies);
+*       if (!token) {
+*         return new Response("Unauthorized", { status: 401 });
+*       }
+*
+*       const user = await validateJWT(token);
+*       const preferences = this.userPrefs.get(cookies) || {
+*         theme: "light",
+*         language: "en",
+*       };
+*
+*       return Response.json({ user, preferences });
+*     },
+*   });
+*
+*   logout = $route({
+*     path: "/logout",
+*     method: "POST",
+*     handler: async ({ reply }) => {
+*       // Clear authentication cookie
+*       this.authToken.clear(reply);
+*       return Response.json({ success: true });
+*     },
+*   });
+* }
+*
+* const alepha = Alepha.create()
+*   .with(AlephaServer)
+*   .with(AlephaServerCookies)
+*   .with(AuthRoutes);
+*
+* run(alepha);
+* ```
+*
+* **Advanced Cookie Management:**
+* ```ts
+* class SessionRoutes {
+*   // Session cookie with custom configuration
+*   sessionId = $cookie({
+*     name: "session_id",
+*     httpOnly: true,
+*     secure: process.env.NODE_ENV === "production",
+*     sameSite: "lax",
+*     path: "/",
+*     maxAge: "2h",
+*     encrypt: true, // Optional encryption
+*   });
+*
+*   // Shopping cart cookie
+*   cart = $cookie({
+*     name: "shopping_cart",
+*     schema: t.object({
+*       items: t.array(t.object({
+*         id: t.string(),
+*         quantity: t.number(),
+*       })),
+*       total: t.number(),
+*     }),
+*     maxAge: "30d",
+*   });
+*
+*   // Tracking consent cookie
+*   consent = $cookie({
+*     name: "tracking_consent",
+*     schema: t.object({
+*       analytics: t.boolean(),
+*       marketing: t.boolean(),
+*       functional: t.boolean(),
+*     }),
+*     maxAge: "1y",
+*   });
+*
+*   updateCart = $route({
+*     path: "/cart",
+*     method: "POST",
+*     schema: {
+*       body: t.object({
+*         productId: t.string(),
+*         quantity: t.number(),
+*       }),
+*     },
+*     handler: async ({ body, cookies, reply }) => {
+*       const currentCart = this.cart.get(cookies) || { items: [], total: 0 };
+*
+*       // Update cart logic
+*       const existingItem = currentCart.items.find(item => item.id === body.productId);
+*       if (existingItem) {
+*         existingItem.quantity = body.quantity;
+*       } else {
+*         currentCart.items.push({ id: body.productId, quantity: body.quantity });
+*       }
+*
+*       // Recalculate total
+*       currentCart.total = await calculateCartTotal(currentCart.items);
+*
+*       // Update cookie
+*       this.cart.set(reply, currentCart);
+*
+*       return Response.json(currentCart);
+*     },
+*   });
+* }
+* ```
+*
+* @see {@link $cookie}
+* @module alepha.server.cookies
+*/
+declare class AlephaServerCookies implements Module {
   readonly name = "alepha.server.cookies";
-  readonly $services: (alepha: any) => void;
+  readonly $services: (alepha: Alepha) => void;
 }
 //#endregion
 export { $cookie, AlephaServerCookies, Cookie, CookieDescriptor, CookieDescriptorOptions, Cookies, ServerCookiesProvider };

package/server/cors.d.ts

@@ -1,12 +1,15 @@
-import * as _alepha_core0 from "@alepha/core";
-import { Alepha, Module } from "@alepha/core";
+import { ServerRouterProvider } from "alepha/server";
+import { Alepha, HookDescriptor, Module } from "alepha";
 
 //#region src/providers/ServerCorsProvider.d.ts
 declare class ServerCorsProvider {
+  protected readonly serverRouterProvider: ServerRouterProvider;
   options: CorsOptions;
-  protected readonly onRequest: _alepha_core0.HookDescriptor<"server:onRequest">;
+  protected readonly onRoute: HookDescriptor<"server:onRoute">;
+  protected readonly onRequest: HookDescriptor<"server:onRequest">;
   isOriginAllowed(origin: string | undefined, allowed: CorsOptions["origin"]): boolean;
 }
+// ---------------------------------------------------------------------------------------------------------------------
 interface CorsOptions {
   origin?: string | string[] | ((origin: string | undefined) => boolean);
   methods: string[];
@@ -16,6 +19,7 @@ interface CorsOptions {
 }
 //#endregion
 //#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
 declare class AlephaServerCors implements Module {
   readonly name = "alepha.server.cors";
   readonly $services: (alepha: Alepha) => void;

package/server/health.d.ts

@@ -1,41 +1,38 @@
-import * as _alepha_server5 from "@alepha/server";
-import { Alepha } from "@alepha/core";
-import { DateTimeProvider } from "@alepha/datetime";
-import * as _sinclair_typebox0 from "@sinclair/typebox";
+import { RouteDescriptor } from "alepha/server";
+import { Alepha, TBoolean, TNumber, TObject, TString } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
 
 //#region src/providers/ServerHealthProvider.d.ts
 
 /**
- * Register `/health` endpoint.
- *
- * - Provides basic health information about the server.
- */
+* Register `/health` endpoint.
+*
+* - Provides basic health information about the server.
+*/
 declare class ServerHealthProvider {
-  protected readonly dateTimeProvider: DateTimeProvider;
+  protected readonly time: DateTimeProvider;
   protected readonly alepha: Alepha;
-  readonly health: _alepha_server5.RouteDescriptor<{
-    response: _sinclair_typebox0.TObject<{
-      message: _sinclair_typebox0.TString;
-      uptime: _sinclair_typebox0.TNumber;
-      date: _sinclair_typebox0.TString;
-      ready: _sinclair_typebox0.TBoolean;
+  readonly health: RouteDescriptor<{
+    response: TObject<{
+      message: TString;
+      uptime: TNumber;
+      date: TString;
+      ready: TBoolean;
     }>;
   }>;
 }
 //#endregion
 //#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
 /**
- * Alepha Server Health Module
- *
- * @description
- * Plugin for Alepha Server that provides health-check endpoints.
- *
- * @see {@link ServerHealthProvider}
- * @module alepha.server.health
- */
+* Plugin for Alepha Server that provides health-check endpoints.
+*
+* @see {@link ServerHealthProvider}
+* @module alepha.server.health
+*/
 declare class AlephaServerHealth {
   readonly name = "alepha.server.health";
-  readonly $services: (alepha: any) => void;
+  readonly $services: (alepha: Alepha) => void;
 }
 //#endregion
 export { AlephaServerHealth, ServerHealthProvider };

package/server/helmet.cjs

@@ -0,0 +1,8 @@
+'use strict';
+var m = require('@alepha/server-helmet');
+Object.keys(m).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return m[k]; }
+	});
+});

package/server/helmet.d.ts

@@ -0,0 +1,70 @@
+import { Alepha, HookDescriptor, Module } from "alepha";
+
+//#region src/providers/ServerHelmetProvider.d.ts
+type CspDirective = string | string[];
+interface CspOptions {
+  directives: {
+    "default-src"?: CspDirective;
+    "script-src"?: CspDirective;
+    "style-src"?: CspDirective;
+    "img-src"?: CspDirective;
+    "connect-src"?: CspDirective;
+    "font-src"?: CspDirective;
+    "object-src"?: CspDirective;
+    "media-src"?: CspDirective;
+    "frame-src"?: CspDirective;
+    sandbox?: CspDirective | boolean;
+    "report-uri"?: string;
+    "child-src"?: CspDirective;
+    "form-action"?: CspDirective;
+    "frame-ancestors"?: CspDirective;
+    "plugin-types"?: CspDirective;
+    "base-uri"?: CspDirective;
+    [key: string]: CspDirective | undefined | boolean;
+  };
+}
+interface HstsOptions {
+  maxAge?: number;
+  includeSubDomains?: boolean;
+  preload?: boolean;
+}
+interface HelmetOptions {
+  isSecure?: boolean;
+  strictTransportSecurity?: HstsOptions | false;
+  xContentTypeOptions?: false;
+  xFrameOptions?: "DENY" | "SAMEORIGIN" | false;
+  xXssProtection?: false;
+  contentSecurityPolicy?: CspOptions | false;
+  referrerPolicy?: "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | false;
+}
+/**
+* Provides a configurable way to apply essential HTTP security headers
+* to every server response, without external dependencies.
+*/
+declare class ServerHelmetProvider {
+  protected readonly alepha: Alepha;
+  /**
+  * The configuration options. These can be overridden during
+  * the application's configuration phase using `alepha.configure()`.
+  */
+  options: HelmetOptions;
+  private buildHeaders;
+  protected readonly onResponse: HookDescriptor<"server:onResponse">;
+}
+//#endregion
+//#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
+/**
+* Automatically adds important HTTP security headers to every response
+* to help protect your application from common web vulnerabilities.
+*
+* @see {@link ServerHelmetProvider}
+* @module alepha.server.helmet
+*/
+declare class AlephaServerHelmet implements Module {
+  readonly name = "alepha.server.helmet";
+  readonly $services: (alepha: Alepha) => void;
+}
+//#endregion
+export { AlephaServerHelmet, CspOptions, HelmetOptions, HstsOptions, ServerHelmetProvider };
+//# sourceMappingURL=index.d.ts.map

package/server/helmet.js

@@ -0,0 +1 @@
+export * from '@alepha/server-helmet'