alepha 0.13.0 → 0.13.2

package/dist/server-security/index.js

@@ -1,4 +1,4 @@
-import { $hook, $inject, $module, Alepha, Descriptor, KIND, createDescriptor } from "alepha";
+import { $hook, $inject, $module, Alepha, KIND, Primitive, createPrimitive } from "alepha";
 import { $permission, $realm, $role, AlephaSecurity, JwtProvider, SecurityProvider, userAccountInfoSchema } from "alepha/security";
 import { $action, AlephaServer, ForbiddenError, HttpError, ServerRouterProvider, UnauthorizedError } from "alepha/server";
 import { randomUUID, timingSafeEqual } from "node:crypto";
@@ -11,11 +11,11 @@ var ServerBasicAuthProvider = class {
 	routerProvider = $inject(ServerRouterProvider);
 	realm = "Secure Area";
 	/**
-	* Registered basic auth descriptors with their configurations
+	* Registered basic auth primitives with their configurations
 	*/
 	registeredAuths = [];
 	/**
-	* Register a basic auth configuration (called by descriptors)
+	* Register a basic auth configuration (called by primitives)
 	*/
 	registerAuth(config) {
 		this.registeredAuths.push(config);
@@ -113,15 +113,15 @@ const isBasicAuth = (value) => {
 };
 
 //#endregion
-//#region src/server-security/descriptors/$basicAuth.ts
+//#region src/server-security/primitives/$basicAuth.ts
 /**
 * Declares HTTP Basic Authentication for server routes.
-* This descriptor provides methods to protect routes with username/password authentication.
+* This primitive provides methods to protect routes with username/password authentication.
 */
 const $basicAuth = (options) => {
-	return createDescriptor(BasicAuthDescriptor, options);
+	return createPrimitive(BasicAuthPrimitive, options);
 };
-var BasicAuthDescriptor = class extends Descriptor {
+var BasicAuthPrimitive = class extends Primitive {
 	serverBasicAuthProvider = $inject(ServerBasicAuthProvider);
 	get name() {
 		return this.options.name ?? `${this.config.propertyKey}`;
@@ -130,7 +130,7 @@ var BasicAuthDescriptor = class extends Descriptor {
 		this.serverBasicAuthProvider.registerAuth(this.options);
 	}
 	/**
-	* Checks basic auth for the given request using this descriptor's configuration.
+	* Checks basic auth for the given request using this primitive's configuration.
 	*/
 	check(request, options) {
 		const mergedOptions = {
@@ -140,7 +140,7 @@ var BasicAuthDescriptor = class extends Descriptor {
 		this.serverBasicAuthProvider.checkAuth(request, mergedOptions);
 	}
 };
-$basicAuth[KIND] = BasicAuthDescriptor;
+$basicAuth[KIND] = BasicAuthPrimitive;
 
 //#endregion
 //#region src/server-security/providers/ServerSecurityProvider.ts
@@ -152,7 +152,7 @@ var ServerSecurityProvider = class {
 	onConfigure = $hook({
 		on: "configure",
 		handler: async () => {
-			for (const action of this.alepha.descriptors($action)) {
+			for (const action of this.alepha.primitives($action)) {
 				if (action.options.disabled || action.options.secure === false || this.securityProvider.getRealms().length === 0) continue;
 				if (typeof action.options.secure !== "object") this.securityProvider.createPermission({
 					name: action.name,
@@ -176,7 +176,7 @@ var ServerSecurityProvider = class {
 				request.user = this.createUserFromLocalFunctionContext(options, permission);
 				const route = action.route;
 				if (typeof route.secure === "object") this.check(request.user, route.secure);
-				this.alepha.state.set("alepha.server.request.user", this.alepha.codec.decode(userAccountInfoSchema, request.user));
+				this.alepha.store.set("alepha.server.request.user", this.alepha.codec.decode(userAccountInfoSchema, request.user));
 			} catch (error) {
 				if (action.options.secure || permission) throw error;
 				this.log.trace("Skipping security check for action");
@@ -200,7 +200,7 @@ var ServerSecurityProvider = class {
 			try {
 				request.user = await this.securityProvider.createUserFromToken(request.headers.authorization, { permission });
 				if (typeof route.secure === "object") this.check(request.user, route.secure);
-				this.alepha.state.set("alepha.server.request.user", this.alepha.codec.decode(userAccountInfoSchema, request.user));
+				this.alepha.store.set("alepha.server.request.user", this.alepha.codec.decode(userAccountInfoSchema, request.user));
 				this.log.trace("User set from request token", {
 					user: request.user,
 					permission
@@ -232,7 +232,7 @@ var ServerSecurityProvider = class {
 		const type = typeof options.user === "string" ? options.user : void 0;
 		let user;
 		const fromContext = this.alepha.context.get("request")?.user;
-		const fromSystem = this.alepha.state.get("alepha.server.security.system.user");
+		const fromSystem = this.alepha.store.get("alepha.server.security.system.user");
 		if (type === "system") user = fromSystem;
 		else if (type === "context") user = fromContext;
 		else user = fromOptions ?? fromContext ?? fromSystem;
@@ -292,7 +292,7 @@ var ServerSecurityProvider = class {
 */
 const AlephaServerSecurity = $module({
 	name: "alepha.server.security",
-	descriptors: [
+	primitives: [
 		$realm,
 		$role,
 		$permission,
@@ -307,5 +307,5 @@ const AlephaServerSecurity = $module({
 });
 
 //#endregion
-export { $basicAuth, AlephaServerSecurity, BasicAuthDescriptor, ServerBasicAuthProvider, ServerSecurityProvider, isBasicAuth };
+export { $basicAuth, AlephaServerSecurity, BasicAuthPrimitive, ServerBasicAuthProvider, ServerSecurityProvider, isBasicAuth };
 //# sourceMappingURL=index.js.map

package/dist/server-security/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["user: UserAccountToken | undefined","ownership: boolean | string | undefined"],"sources":["../../src/server-security/providers/ServerBasicAuthProvider.ts","../../src/server-security/descriptors/$basicAuth.ts","../../src/server-security/providers/ServerSecurityProvider.ts","../../src/server-security/index.ts"],"sourcesContent":["import { timingSafeEqual } from \"node:crypto\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  HttpError,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BasicAuthOptions {\n  username: string;\n  password: string;\n}\n\nexport interface BasicAuthDescriptorConfig extends BasicAuthOptions {\n  /** Name identifier for this basic auth (default: property key) */\n  name?: string;\n  /** Path patterns to match (supports wildcards like /devtools/*) */\n  paths?: string[];\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ServerBasicAuthProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly routerProvider = $inject(ServerRouterProvider);\n  protected readonly realm = \"Secure Area\";\n\n  /**\n   * Registered basic auth descriptors with their configurations\n   */\n  public readonly registeredAuths: BasicAuthDescriptorConfig[] = [];\n\n  /**\n   * Register a basic auth configuration (called by descriptors)\n   */\n  public registerAuth(config: BasicAuthDescriptorConfig): void {\n    this.registeredAuths.push(config);\n  }\n\n  public readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      for (const auth of this.registeredAuths) {\n        if (auth.paths) {\n          for (const pattern of auth.paths) {\n            const matchedRoutes = this.routerProvider.getRoutes(pattern);\n            for (const route of matchedRoutes) {\n              route.secure = {\n                basic: {\n                  username: auth.username,\n                  password: auth.password,\n                },\n              };\n            }\n          }\n        }\n      }\n\n      if (this.registeredAuths.length > 0) {\n        this.log.info(\n          `Initialized with ${this.registeredAuths.length} registered basic-auth configurations.`,\n        );\n      }\n    },\n  });\n\n  /**\n   * Hook into server:onRequest to check basic auth\n   */\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      const routeAuth = route.secure;\n      if (\n        typeof routeAuth === \"object\" &&\n        \"basic\" in routeAuth &&\n        routeAuth.basic\n      ) {\n        this.checkAuth(request, routeAuth.basic);\n      }\n    },\n  });\n\n  /**\n   * Hook into action:onRequest to check basic auth for actions\n   */\n  public readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request }) => {\n      const routeAuth = action.route.secure;\n      if (isBasicAuth(routeAuth)) {\n        this.checkAuth(request, routeAuth.basic);\n      }\n    },\n  });\n\n  /**\n   * Check basic authentication\n   */\n  public checkAuth(request: ServerRequest, options: BasicAuthOptions): void {\n    const authHeader = request.headers?.authorization;\n\n    if (!authHeader || !authHeader.startsWith(\"Basic \")) {\n      this.sendAuthRequired(request);\n      throw new HttpError({\n        status: 401,\n        message: \"Authentication required\",\n      });\n    }\n\n    // decode base64 credentials\n    const base64Credentials = authHeader.slice(6); // Remove \"Basic \"\n    const credentials = Buffer.from(base64Credentials, \"base64\").toString(\n      \"utf-8\",\n    );\n\n    // split only on the first colon to handle passwords with colons\n    const colonIndex = credentials.indexOf(\":\");\n    const username =\n      colonIndex !== -1 ? credentials.slice(0, colonIndex) : credentials;\n    const password = colonIndex !== -1 ? credentials.slice(colonIndex + 1) : \"\";\n\n    // verify credentials using timing-safe comparison to prevent timing attacks\n    const isValid = this.timingSafeCredentialCheck(\n      username,\n      password,\n      options.username,\n      options.password,\n    );\n\n    if (!isValid) {\n      this.sendAuthRequired(request);\n      this.log.warn(`Failed basic auth attempt for user`, {\n        username,\n      });\n      throw new HttpError({\n        status: 401,\n        message: \"Invalid credentials\",\n      });\n    }\n  }\n\n  /**\n   * Performs a timing-safe comparison of credentials to prevent timing attacks.\n   * Always compares both username and password to avoid leaking which one is wrong.\n   */\n  protected timingSafeCredentialCheck(\n    inputUsername: string,\n    inputPassword: string,\n    expectedUsername: string,\n    expectedPassword: string,\n  ): boolean {\n    // Convert to buffers for timing-safe comparison\n    const inputUserBuf = Buffer.from(inputUsername, \"utf-8\");\n    const expectedUserBuf = Buffer.from(expectedUsername, \"utf-8\");\n    const inputPassBuf = Buffer.from(inputPassword, \"utf-8\");\n    const expectedPassBuf = Buffer.from(expectedPassword, \"utf-8\");\n\n    // timingSafeEqual requires same-length buffers\n    // When lengths differ, we compare against a dummy buffer to maintain constant time\n    const userMatch = this.safeCompare(inputUserBuf, expectedUserBuf);\n    const passMatch = this.safeCompare(inputPassBuf, expectedPassBuf);\n\n    // Both must match - bitwise AND avoids short-circuit evaluation\n    // eslint-disable-next-line no-bitwise\n    return (userMatch & passMatch) === 1;\n  }\n\n  /**\n   * Compares two buffers in constant time, handling different lengths safely.\n   * Returns 1 if equal, 0 if not equal.\n   */\n  protected safeCompare(input: Buffer, expected: Buffer): number {\n    // If lengths differ, compare input against itself to maintain timing\n    // but return 0 (not equal)\n    if (input.length !== expected.length) {\n      // Still perform a comparison to keep timing consistent\n      timingSafeEqual(input, input);\n      return 0;\n    }\n\n    return timingSafeEqual(input, expected) ? 1 : 0;\n  }\n\n  /**\n   * Send WWW-Authenticate header\n   */\n  protected sendAuthRequired(request: ServerRequest): void {\n    request.reply.setHeader(\"WWW-Authenticate\", `Basic realm=\"${this.realm}\"`);\n  }\n}\n\nexport const isBasicAuth = (\n  value: unknown,\n): value is { basic: BasicAuthOptions } => {\n  return (\n    typeof value === \"object\" && !!value && \"basic\" in value && !!value.basic\n  );\n};\n","import { $inject, createDescriptor, Descriptor, KIND } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\nimport type {\n  BasicAuthDescriptorConfig,\n  BasicAuthOptions,\n} from \"../providers/ServerBasicAuthProvider.ts\";\nimport { ServerBasicAuthProvider } from \"../providers/ServerBasicAuthProvider.ts\";\n\n/**\n * Declares HTTP Basic Authentication for server routes.\n * This descriptor provides methods to protect routes with username/password authentication.\n */\nexport const $basicAuth = (\n  options: BasicAuthDescriptorConfig,\n): AbstractBasicAuthDescriptor => {\n  return createDescriptor(BasicAuthDescriptor, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface AbstractBasicAuthDescriptor {\n  readonly name: string;\n  readonly options: BasicAuthDescriptorConfig;\n  check(request: ServerRequest, options?: BasicAuthOptions): void;\n}\n\nexport class BasicAuthDescriptor\n  extends Descriptor<BasicAuthDescriptorConfig>\n  implements AbstractBasicAuthDescriptor\n{\n  protected readonly serverBasicAuthProvider = $inject(ServerBasicAuthProvider);\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  protected onInit() {\n    // Register this auth configuration with the provider\n    this.serverBasicAuthProvider.registerAuth(this.options);\n  }\n\n  /**\n   * Checks basic auth for the given request using this descriptor's configuration.\n   */\n  public check(request: ServerRequest, options?: BasicAuthOptions): void {\n    const mergedOptions = { ...this.options, ...options };\n    this.serverBasicAuthProvider.checkAuth(request, mergedOptions);\n  }\n}\n\n$basicAuth[KIND] = BasicAuthDescriptor;\n","import { randomUUID } from \"node:crypto\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  JwtProvider,\n  type Permission,\n  SecurityProvider,\n  type UserAccountToken,\n  userAccountInfoSchema,\n} from \"alepha/security\";\nimport {\n  $action,\n  ForbiddenError,\n  type ServerRequest,\n  UnauthorizedError,\n} from \"alepha/server\";\nimport {\n  type BasicAuthOptions,\n  isBasicAuth,\n} from \"./ServerBasicAuthProvider.ts\";\n\nexport class ServerSecurityProvider {\n  protected readonly log = $logger();\n  protected readonly securityProvider = $inject(SecurityProvider);\n  protected readonly jwtProvider = $inject(JwtProvider);\n  protected readonly alepha = $inject(Alepha);\n\n  protected readonly onConfigure = $hook({\n    on: \"configure\",\n    handler: async () => {\n      for (const action of this.alepha.descriptors($action)) {\n        // -------------------------------------------------------------------------------------------------------------\n        // if the action is disabled or not secure, we do NOT create a permission for it\n        // -------------------------------------------------------------------------------------------------------------\n        if (\n          action.options.disabled ||\n          action.options.secure === false ||\n          this.securityProvider.getRealms().length === 0\n        ) {\n          continue;\n        }\n\n        const secure = action.options.secure;\n        if (typeof secure !== \"object\") {\n          this.securityProvider.createPermission({\n            name: action.name,\n            group: action.group,\n            method: action.route.method,\n            path: action.route.path,\n          });\n        }\n      }\n    },\n  });\n\n  // -------------------------------------------------------------------------------------------------------------------\n\n  protected readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request, options }) => {\n      // if you set explicitly secure: false, we assume you don't want any security check\n      // but only if no user is provided in options\n      if (action.options.secure === false && !options.user) {\n        this.log.trace(\"Skipping security check for route\");\n        return;\n      }\n\n      if (isBasicAuth(action.route.secure)) {\n        return;\n      }\n\n      const permission = this.securityProvider\n        .getPermissions()\n        .find(\n          (it) =>\n            it.path === action.route.path && it.method === action.route.method,\n        );\n\n      try {\n        request.user = this.createUserFromLocalFunctionContext(\n          options,\n          permission,\n        );\n\n        const route = action.route;\n        if (typeof route.secure === \"object\") {\n          this.check(request.user, route.secure);\n        }\n\n        this.alepha.state.set(\n          \"alepha.server.request.user\",\n          this.alepha.codec.decode(userAccountInfoSchema, request.user),\n        );\n      } catch (error) {\n        if (action.options.secure || permission) {\n          throw error;\n        }\n        // else, we skip the security check\n        this.log.trace(\"Skipping security check for action\");\n      }\n    },\n  });\n\n  protected readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    priority: \"last\",\n    handler: async ({ request, route }) => {\n      // if you set explicitly secure: false, we assume you don't want any security check\n      if (route.secure === false) {\n        this.log.trace(\n          \"Skipping security check for route - explicitly disabled\",\n        );\n        return;\n      }\n\n      if (isBasicAuth(route.secure)) {\n        return;\n      }\n\n      const permission = this.securityProvider\n        .getPermissions()\n        .find((it) => it.path === route.path && it.method === route.method);\n\n      if (!request.headers.authorization && !route.secure && !permission) {\n        this.log.trace(\n          \"Skipping security check for route - no authorization header and not secure\",\n        );\n        return;\n      }\n\n      try {\n        // set user to request\n        request.user = await this.securityProvider.createUserFromToken(\n          request.headers.authorization,\n          { permission },\n        );\n\n        if (typeof route.secure === \"object\") {\n          this.check(request.user, route.secure);\n        }\n\n        this.alepha.state.set(\n          \"alepha.server.request.user\",\n          // remove sensitive info\n          this.alepha.codec.decode(userAccountInfoSchema, request.user),\n        );\n\n        this.log.trace(\"User set from request token\", {\n          user: request.user,\n          permission,\n        });\n      } catch (error) {\n        if (route.secure || permission) {\n          throw error;\n        }\n\n        // else, we skip the security check\n        this.log.trace(\n          \"Skipping security check for route - error occurred\",\n          error,\n        );\n      }\n    },\n  });\n\n  // -------------------------------------------------------------------------------------------------------------------\n\n  protected check(user: UserAccountToken, secure: ServerRouteSecure) {\n    if (secure.realm) {\n      if (user.realm !== secure.realm) {\n        throw new ForbiddenError(\n          `User must belong to realm '${secure.realm}' to access this route`,\n        );\n      }\n    }\n  }\n\n  /**\n   * Get the user account token for a local action call.\n   * There are three possible sources for the user:\n   * - `options.user`: the user passed in the options\n   * - `\"system\"`: the system user from the state (you MUST set state `server.security.system.user`)\n   * - `\"context\"`: the user from the request context (you MUST be in an HTTP request context)\n   *\n   * Priority order: `options.user` > `\"system\"` > `\"context\"`.\n   *\n   * In testing environment, if no user is provided, a test user is created based on the SecurityProvider's roles.\n   */\n  protected createUserFromLocalFunctionContext(\n    options: { user?: UserAccountToken | \"system\" | \"context\" },\n    permission?: Permission,\n  ): UserAccountToken {\n    const fromOptions =\n      typeof options.user === \"object\" ? options.user : undefined;\n\n    const type = typeof options.user === \"string\" ? options.user : undefined;\n\n    let user: UserAccountToken | undefined;\n\n    const fromContext = this.alepha.context.get<ServerRequest>(\"request\")?.user;\n    const fromSystem = this.alepha.state.get(\n      \"alepha.server.security.system.user\",\n    );\n\n    if (type === \"system\") {\n      user = fromSystem;\n    } else if (type === \"context\") {\n      user = fromContext;\n    } else {\n      user = fromOptions ?? fromContext ?? fromSystem;\n    }\n\n    if (!user) {\n      // in testing mode, we create a test user\n      if (this.alepha.isTest() && !(\"user\" in options)) {\n        return this.createTestUser();\n      }\n\n      throw new UnauthorizedError(\"User is required for calling this action\");\n    }\n\n    const roles =\n      user.roles ??\n      (this.alepha.isTest()\n        ? this.securityProvider.getRoles().map((role) => role.name)\n        : []);\n    let ownership: boolean | string | undefined;\n\n    if (permission) {\n      const result = this.securityProvider.checkPermission(\n        permission,\n        ...roles,\n      );\n      if (!result.isAuthorized) {\n        throw new ForbiddenError(\n          `Permission '${this.securityProvider.permissionToString(permission)}' is required for this route`,\n        );\n      }\n      ownership = result.ownership;\n    }\n\n    // create a new user object with ownership if needed\n    return {\n      ...user,\n      ownership,\n    };\n  }\n\n  // ---------------------------------------------------------------------------------------------------------------\n  // TESTING ONLY\n  // ---------------------------------------------------------------------------------------------------------------\n\n  protected createTestUser(): UserAccountToken {\n    return {\n      id: randomUUID(),\n      name: \"Test\",\n      roles: this.securityProvider.getRoles().map((role) => role.name),\n    };\n  }\n\n  protected readonly onClientRequest = $hook({\n    on: \"client:onRequest\",\n    handler: async ({ request, options }) => {\n      if (!this.alepha.isTest()) {\n        return;\n      }\n\n      // skip helper if user is explicitly set to undefined\n      if (\"user\" in options && options.user === undefined) {\n        return;\n      }\n\n      request.headers = new Headers(request.headers);\n\n      if (!request.headers.has(\"authorization\")) {\n        const test = this.createTestUser();\n        const user =\n          typeof options?.user === \"object\" ? options.user : undefined;\n        const sub = user?.id ?? test.id;\n        const roles = user?.roles ?? test.roles;\n\n        const token = await this.jwtProvider.create(\n          {\n            sub,\n            roles,\n          },\n          user?.realm ?? this.securityProvider.getRealms()[0]?.name,\n        );\n\n        request.headers.set(\"authorization\", `Bearer ${token}`);\n      }\n    },\n  });\n}\n\nexport type ServerRouteSecure = {\n  realm?: string;\n  basic?: BasicAuthOptions;\n};\n","import { $module } from \"alepha\";\nimport {\n  $permission,\n  $realm,\n  $role,\n  AlephaSecurity,\n  type UserAccount,\n  type UserAccountToken,\n} from \"alepha/security\";\nimport { AlephaServer, type FetchOptions } from \"alepha/server\";\nimport { $basicAuth } from \"./descriptors/$basicAuth.ts\";\nimport { ServerBasicAuthProvider } from \"./providers/ServerBasicAuthProvider.ts\";\nimport {\n  type ServerRouteSecure,\n  ServerSecurityProvider,\n} from \"./providers/ServerSecurityProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$basicAuth.ts\";\nexport * from \"./providers/ServerBasicAuthProvider.ts\";\nexport * from \"./providers/ServerSecurityProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  interface State {\n    /**\n     * Real (or fake) user account, used for internal actions.\n     *\n     * If you define this, you assume that all actions are executed by this user by default.\n     * > To force a different user, you need to pass it explicitly in the options.\n     */\n\n    \"alepha.server.security.system.user\"?: UserAccountToken;\n\n    /**\n     * The authenticated user account attached to the server request state.\n     *\n     * @internal\n     */\n    \"alepha.server.request.user\"?: UserAccount;\n  }\n}\n\ndeclare module \"alepha/server\" {\n  interface ServerRequest<TConfig> {\n    user?: UserAccountToken; // for all routes, user is maybe present\n  }\n\n  interface ServerActionRequest<TConfig> {\n    user: UserAccountToken; // for actions, user is always present\n  }\n\n  interface ServerRoute {\n    /**\n     * If true, the route will be protected by the security provider.\n     * All actions are secure by default, but you can disable it for specific actions.\n     */\n    secure?: boolean | ServerRouteSecure;\n  }\n\n  interface ClientRequestOptions extends FetchOptions {\n    /**\n     * Forward user from the previous request.\n     * If \"system\", use system user. @see {ServerSecurityProvider.localSystemUser}\n     * If \"context\", use the user from the current context (e.g. request).\n     *\n     * @default \"system\" if provided, else \"context\" if available.\n     */\n    user?: UserAccountToken | \"system\" | \"context\";\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Server that provides security features. Based on the Alepha Security module.\n *\n * By default, all $action will be guarded by a permission check.\n *\n * @see {@link ServerSecurityProvider}\n * @module alepha.server.security\n */\nexport const AlephaServerSecurity = $module({\n  name: \"alepha.server.security\",\n  descriptors: [$realm, $role, $permission, $basicAuth],\n  services: [\n    AlephaServer,\n    AlephaSecurity,\n    ServerSecurityProvider,\n    ServerBasicAuthProvider,\n  ],\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["user: UserAccountToken | undefined","ownership: boolean | string | undefined"],"sources":["../../src/server-security/providers/ServerBasicAuthProvider.ts","../../src/server-security/primitives/$basicAuth.ts","../../src/server-security/providers/ServerSecurityProvider.ts","../../src/server-security/index.ts"],"sourcesContent":["import { timingSafeEqual } from \"node:crypto\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  HttpError,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BasicAuthOptions {\n  username: string;\n  password: string;\n}\n\nexport interface BasicAuthPrimitiveConfig extends BasicAuthOptions {\n  /** Name identifier for this basic auth (default: property key) */\n  name?: string;\n  /** Path patterns to match (supports wildcards like /devtools/*) */\n  paths?: string[];\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ServerBasicAuthProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly routerProvider = $inject(ServerRouterProvider);\n  protected readonly realm = \"Secure Area\";\n\n  /**\n   * Registered basic auth primitives with their configurations\n   */\n  public readonly registeredAuths: BasicAuthPrimitiveConfig[] = [];\n\n  /**\n   * Register a basic auth configuration (called by primitives)\n   */\n  public registerAuth(config: BasicAuthPrimitiveConfig): void {\n    this.registeredAuths.push(config);\n  }\n\n  public readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      for (const auth of this.registeredAuths) {\n        if (auth.paths) {\n          for (const pattern of auth.paths) {\n            const matchedRoutes = this.routerProvider.getRoutes(pattern);\n            for (const route of matchedRoutes) {\n              route.secure = {\n                basic: {\n                  username: auth.username,\n                  password: auth.password,\n                },\n              };\n            }\n          }\n        }\n      }\n\n      if (this.registeredAuths.length > 0) {\n        this.log.info(\n          `Initialized with ${this.registeredAuths.length} registered basic-auth configurations.`,\n        );\n      }\n    },\n  });\n\n  /**\n   * Hook into server:onRequest to check basic auth\n   */\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      const routeAuth = route.secure;\n      if (\n        typeof routeAuth === \"object\" &&\n        \"basic\" in routeAuth &&\n        routeAuth.basic\n      ) {\n        this.checkAuth(request, routeAuth.basic);\n      }\n    },\n  });\n\n  /**\n   * Hook into action:onRequest to check basic auth for actions\n   */\n  public readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request }) => {\n      const routeAuth = action.route.secure;\n      if (isBasicAuth(routeAuth)) {\n        this.checkAuth(request, routeAuth.basic);\n      }\n    },\n  });\n\n  /**\n   * Check basic authentication\n   */\n  public checkAuth(request: ServerRequest, options: BasicAuthOptions): void {\n    const authHeader = request.headers?.authorization;\n\n    if (!authHeader || !authHeader.startsWith(\"Basic \")) {\n      this.sendAuthRequired(request);\n      throw new HttpError({\n        status: 401,\n        message: \"Authentication required\",\n      });\n    }\n\n    // decode base64 credentials\n    const base64Credentials = authHeader.slice(6); // Remove \"Basic \"\n    const credentials = Buffer.from(base64Credentials, \"base64\").toString(\n      \"utf-8\",\n    );\n\n    // split only on the first colon to handle passwords with colons\n    const colonIndex = credentials.indexOf(\":\");\n    const username =\n      colonIndex !== -1 ? credentials.slice(0, colonIndex) : credentials;\n    const password = colonIndex !== -1 ? credentials.slice(colonIndex + 1) : \"\";\n\n    // verify credentials using timing-safe comparison to prevent timing attacks\n    const isValid = this.timingSafeCredentialCheck(\n      username,\n      password,\n      options.username,\n      options.password,\n    );\n\n    if (!isValid) {\n      this.sendAuthRequired(request);\n      this.log.warn(`Failed basic auth attempt for user`, {\n        username,\n      });\n      throw new HttpError({\n        status: 401,\n        message: \"Invalid credentials\",\n      });\n    }\n  }\n\n  /**\n   * Performs a timing-safe comparison of credentials to prevent timing attacks.\n   * Always compares both username and password to avoid leaking which one is wrong.\n   */\n  protected timingSafeCredentialCheck(\n    inputUsername: string,\n    inputPassword: string,\n    expectedUsername: string,\n    expectedPassword: string,\n  ): boolean {\n    // Convert to buffers for timing-safe comparison\n    const inputUserBuf = Buffer.from(inputUsername, \"utf-8\");\n    const expectedUserBuf = Buffer.from(expectedUsername, \"utf-8\");\n    const inputPassBuf = Buffer.from(inputPassword, \"utf-8\");\n    const expectedPassBuf = Buffer.from(expectedPassword, \"utf-8\");\n\n    // timingSafeEqual requires same-length buffers\n    // When lengths differ, we compare against a dummy buffer to maintain constant time\n    const userMatch = this.safeCompare(inputUserBuf, expectedUserBuf);\n    const passMatch = this.safeCompare(inputPassBuf, expectedPassBuf);\n\n    // Both must match - bitwise AND avoids short-circuit evaluation\n    // eslint-disable-next-line no-bitwise\n    return (userMatch & passMatch) === 1;\n  }\n\n  /**\n   * Compares two buffers in constant time, handling different lengths safely.\n   * Returns 1 if equal, 0 if not equal.\n   */\n  protected safeCompare(input: Buffer, expected: Buffer): number {\n    // If lengths differ, compare input against itself to maintain timing\n    // but return 0 (not equal)\n    if (input.length !== expected.length) {\n      // Still perform a comparison to keep timing consistent\n      timingSafeEqual(input, input);\n      return 0;\n    }\n\n    return timingSafeEqual(input, expected) ? 1 : 0;\n  }\n\n  /**\n   * Send WWW-Authenticate header\n   */\n  protected sendAuthRequired(request: ServerRequest): void {\n    request.reply.setHeader(\"WWW-Authenticate\", `Basic realm=\"${this.realm}\"`);\n  }\n}\n\nexport const isBasicAuth = (\n  value: unknown,\n): value is { basic: BasicAuthOptions } => {\n  return (\n    typeof value === \"object\" && !!value && \"basic\" in value && !!value.basic\n  );\n};\n","import { $inject, createPrimitive, KIND, Primitive } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\nimport type {\n  BasicAuthOptions,\n  BasicAuthPrimitiveConfig,\n} from \"../providers/ServerBasicAuthProvider.ts\";\nimport { ServerBasicAuthProvider } from \"../providers/ServerBasicAuthProvider.ts\";\n\n/**\n * Declares HTTP Basic Authentication for server routes.\n * This primitive provides methods to protect routes with username/password authentication.\n */\nexport const $basicAuth = (\n  options: BasicAuthPrimitiveConfig,\n): AbstractBasicAuthPrimitive => {\n  return createPrimitive(BasicAuthPrimitive, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface AbstractBasicAuthPrimitive {\n  readonly name: string;\n  readonly options: BasicAuthPrimitiveConfig;\n  check(request: ServerRequest, options?: BasicAuthOptions): void;\n}\n\nexport class BasicAuthPrimitive\n  extends Primitive<BasicAuthPrimitiveConfig>\n  implements AbstractBasicAuthPrimitive\n{\n  protected readonly serverBasicAuthProvider = $inject(ServerBasicAuthProvider);\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  protected onInit() {\n    // Register this auth configuration with the provider\n    this.serverBasicAuthProvider.registerAuth(this.options);\n  }\n\n  /**\n   * Checks basic auth for the given request using this primitive's configuration.\n   */\n  public check(request: ServerRequest, options?: BasicAuthOptions): void {\n    const mergedOptions = { ...this.options, ...options };\n    this.serverBasicAuthProvider.checkAuth(request, mergedOptions);\n  }\n}\n\n$basicAuth[KIND] = BasicAuthPrimitive;\n","import { randomUUID } from \"node:crypto\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  JwtProvider,\n  type Permission,\n  SecurityProvider,\n  type UserAccountToken,\n  userAccountInfoSchema,\n} from \"alepha/security\";\nimport {\n  $action,\n  ForbiddenError,\n  type ServerRequest,\n  UnauthorizedError,\n} from \"alepha/server\";\nimport {\n  type BasicAuthOptions,\n  isBasicAuth,\n} from \"./ServerBasicAuthProvider.ts\";\n\nexport class ServerSecurityProvider {\n  protected readonly log = $logger();\n  protected readonly securityProvider = $inject(SecurityProvider);\n  protected readonly jwtProvider = $inject(JwtProvider);\n  protected readonly alepha = $inject(Alepha);\n\n  protected readonly onConfigure = $hook({\n    on: \"configure\",\n    handler: async () => {\n      for (const action of this.alepha.primitives($action)) {\n        // -------------------------------------------------------------------------------------------------------------\n        // if the action is disabled or not secure, we do NOT create a permission for it\n        // -------------------------------------------------------------------------------------------------------------\n        if (\n          action.options.disabled ||\n          action.options.secure === false ||\n          this.securityProvider.getRealms().length === 0\n        ) {\n          continue;\n        }\n\n        const secure = action.options.secure;\n        if (typeof secure !== \"object\") {\n          this.securityProvider.createPermission({\n            name: action.name,\n            group: action.group,\n            method: action.route.method,\n            path: action.route.path,\n          });\n        }\n      }\n    },\n  });\n\n  // -------------------------------------------------------------------------------------------------------------------\n\n  protected readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request, options }) => {\n      // if you set explicitly secure: false, we assume you don't want any security check\n      // but only if no user is provided in options\n      if (action.options.secure === false && !options.user) {\n        this.log.trace(\"Skipping security check for route\");\n        return;\n      }\n\n      if (isBasicAuth(action.route.secure)) {\n        return;\n      }\n\n      const permission = this.securityProvider\n        .getPermissions()\n        .find(\n          (it) =>\n            it.path === action.route.path && it.method === action.route.method,\n        );\n\n      try {\n        request.user = this.createUserFromLocalFunctionContext(\n          options,\n          permission,\n        );\n\n        const route = action.route;\n        if (typeof route.secure === \"object\") {\n          this.check(request.user, route.secure);\n        }\n\n        this.alepha.store.set(\n          \"alepha.server.request.user\",\n          this.alepha.codec.decode(userAccountInfoSchema, request.user),\n        );\n      } catch (error) {\n        if (action.options.secure || permission) {\n          throw error;\n        }\n        // else, we skip the security check\n        this.log.trace(\"Skipping security check for action\");\n      }\n    },\n  });\n\n  protected readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    priority: \"last\",\n    handler: async ({ request, route }) => {\n      // if you set explicitly secure: false, we assume you don't want any security check\n      if (route.secure === false) {\n        this.log.trace(\n          \"Skipping security check for route - explicitly disabled\",\n        );\n        return;\n      }\n\n      if (isBasicAuth(route.secure)) {\n        return;\n      }\n\n      const permission = this.securityProvider\n        .getPermissions()\n        .find((it) => it.path === route.path && it.method === route.method);\n\n      if (!request.headers.authorization && !route.secure && !permission) {\n        this.log.trace(\n          \"Skipping security check for route - no authorization header and not secure\",\n        );\n        return;\n      }\n\n      try {\n        // set user to request\n        request.user = await this.securityProvider.createUserFromToken(\n          request.headers.authorization,\n          { permission },\n        );\n\n        if (typeof route.secure === \"object\") {\n          this.check(request.user, route.secure);\n        }\n\n        this.alepha.store.set(\n          \"alepha.server.request.user\",\n          // remove sensitive info\n          this.alepha.codec.decode(userAccountInfoSchema, request.user),\n        );\n\n        this.log.trace(\"User set from request token\", {\n          user: request.user,\n          permission,\n        });\n      } catch (error) {\n        if (route.secure || permission) {\n          throw error;\n        }\n\n        // else, we skip the security check\n        this.log.trace(\n          \"Skipping security check for route - error occurred\",\n          error,\n        );\n      }\n    },\n  });\n\n  // -------------------------------------------------------------------------------------------------------------------\n\n  protected check(user: UserAccountToken, secure: ServerRouteSecure) {\n    if (secure.realm) {\n      if (user.realm !== secure.realm) {\n        throw new ForbiddenError(\n          `User must belong to realm '${secure.realm}' to access this route`,\n        );\n      }\n    }\n  }\n\n  /**\n   * Get the user account token for a local action call.\n   * There are three possible sources for the user:\n   * - `options.user`: the user passed in the options\n   * - `\"system\"`: the system user from the state (you MUST set state `server.security.system.user`)\n   * - `\"context\"`: the user from the request context (you MUST be in an HTTP request context)\n   *\n   * Priority order: `options.user` > `\"system\"` > `\"context\"`.\n   *\n   * In testing environment, if no user is provided, a test user is created based on the SecurityProvider's roles.\n   */\n  protected createUserFromLocalFunctionContext(\n    options: { user?: UserAccountToken | \"system\" | \"context\" },\n    permission?: Permission,\n  ): UserAccountToken {\n    const fromOptions =\n      typeof options.user === \"object\" ? options.user : undefined;\n\n    const type = typeof options.user === \"string\" ? options.user : undefined;\n\n    let user: UserAccountToken | undefined;\n\n    const fromContext = this.alepha.context.get<ServerRequest>(\"request\")?.user;\n    const fromSystem = this.alepha.store.get(\n      \"alepha.server.security.system.user\",\n    );\n\n    if (type === \"system\") {\n      user = fromSystem;\n    } else if (type === \"context\") {\n      user = fromContext;\n    } else {\n      user = fromOptions ?? fromContext ?? fromSystem;\n    }\n\n    if (!user) {\n      // in testing mode, we create a test user\n      if (this.alepha.isTest() && !(\"user\" in options)) {\n        return this.createTestUser();\n      }\n\n      throw new UnauthorizedError(\"User is required for calling this action\");\n    }\n\n    const roles =\n      user.roles ??\n      (this.alepha.isTest()\n        ? this.securityProvider.getRoles().map((role) => role.name)\n        : []);\n    let ownership: boolean | string | undefined;\n\n    if (permission) {\n      const result = this.securityProvider.checkPermission(\n        permission,\n        ...roles,\n      );\n      if (!result.isAuthorized) {\n        throw new ForbiddenError(\n          `Permission '${this.securityProvider.permissionToString(permission)}' is required for this route`,\n        );\n      }\n      ownership = result.ownership;\n    }\n\n    // create a new user object with ownership if needed\n    return {\n      ...user,\n      ownership,\n    };\n  }\n\n  // ---------------------------------------------------------------------------------------------------------------\n  // TESTING ONLY\n  // ---------------------------------------------------------------------------------------------------------------\n\n  protected createTestUser(): UserAccountToken {\n    return {\n      id: randomUUID(),\n      name: \"Test\",\n      roles: this.securityProvider.getRoles().map((role) => role.name),\n    };\n  }\n\n  protected readonly onClientRequest = $hook({\n    on: \"client:onRequest\",\n    handler: async ({ request, options }) => {\n      if (!this.alepha.isTest()) {\n        return;\n      }\n\n      // skip helper if user is explicitly set to undefined\n      if (\"user\" in options && options.user === undefined) {\n        return;\n      }\n\n      request.headers = new Headers(request.headers);\n\n      if (!request.headers.has(\"authorization\")) {\n        const test = this.createTestUser();\n        const user =\n          typeof options?.user === \"object\" ? options.user : undefined;\n        const sub = user?.id ?? test.id;\n        const roles = user?.roles ?? test.roles;\n\n        const token = await this.jwtProvider.create(\n          {\n            sub,\n            roles,\n          },\n          user?.realm ?? this.securityProvider.getRealms()[0]?.name,\n        );\n\n        request.headers.set(\"authorization\", `Bearer ${token}`);\n      }\n    },\n  });\n}\n\nexport type ServerRouteSecure = {\n  realm?: string;\n  basic?: BasicAuthOptions;\n};\n","import { $module } from \"alepha\";\nimport {\n  $permission,\n  $realm,\n  $role,\n  AlephaSecurity,\n  type UserAccount,\n  type UserAccountToken,\n} from \"alepha/security\";\nimport { AlephaServer, type FetchOptions } from \"alepha/server\";\nimport { $basicAuth } from \"./primitives/$basicAuth.ts\";\nimport { ServerBasicAuthProvider } from \"./providers/ServerBasicAuthProvider.ts\";\nimport {\n  type ServerRouteSecure,\n  ServerSecurityProvider,\n} from \"./providers/ServerSecurityProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$basicAuth.ts\";\nexport * from \"./providers/ServerBasicAuthProvider.ts\";\nexport * from \"./providers/ServerSecurityProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  interface State {\n    /**\n     * Real (or fake) user account, used for internal actions.\n     *\n     * If you define this, you assume that all actions are executed by this user by default.\n     * > To force a different user, you need to pass it explicitly in the options.\n     */\n\n    \"alepha.server.security.system.user\"?: UserAccountToken;\n\n    /**\n     * The authenticated user account attached to the server request state.\n     *\n     * @internal\n     */\n    \"alepha.server.request.user\"?: UserAccount;\n  }\n}\n\ndeclare module \"alepha/server\" {\n  interface ServerRequest<TConfig> {\n    user?: UserAccountToken; // for all routes, user is maybe present\n  }\n\n  interface ServerActionRequest<TConfig> {\n    user: UserAccountToken; // for actions, user is always present\n  }\n\n  interface ServerRoute {\n    /**\n     * If true, the route will be protected by the security provider.\n     * All actions are secure by default, but you can disable it for specific actions.\n     */\n    secure?: boolean | ServerRouteSecure;\n  }\n\n  interface ClientRequestOptions extends FetchOptions {\n    /**\n     * Forward user from the previous request.\n     * If \"system\", use system user. @see {ServerSecurityProvider.localSystemUser}\n     * If \"context\", use the user from the current context (e.g. request).\n     *\n     * @default \"system\" if provided, else \"context\" if available.\n     */\n    user?: UserAccountToken | \"system\" | \"context\";\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Server that provides security features. Based on the Alepha Security module.\n *\n * By default, all $action will be guarded by a permission check.\n *\n * @see {@link ServerSecurityProvider}\n * @module alepha.server.security\n */\nexport const AlephaServerSecurity = $module({\n  name: \"alepha.server.security\",\n  primitives: [$realm, $role, $permission, $basicAuth],\n  services: [\n    AlephaServer,\n    AlephaSecurity,\n    ServerSecurityProvider,\n    ServerBasicAuthProvider,\n  ],\n});\n"],"mappings":"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"}

package/dist/server-static/index.d.ts

@@ -1,19 +1,19 @@
 import * as alepha1 from "alepha";
-import { Alepha, Descriptor, KIND } from "alepha";
+import { Alepha, KIND, Primitive } from "alepha";
 import { ServerHandler, ServerRouterProvider } from "alepha/server";
 import { DateTimeProvider, DurationLike } from "alepha/datetime";
 import { FileDetector } from "alepha/file";
 import * as alepha_logger0 from "alepha/logger";
 
-//#region src/server-static/descriptors/$serve.d.ts
+//#region src/server-static/primitives/$serve.d.ts
 /**
  * Create a new static file handler.
  */
 declare const $serve: {
-  (options?: ServeDescriptorOptions): ServeDescriptor;
-  [KIND]: typeof ServeDescriptor;
+  (options?: ServePrimitiveOptions): ServePrimitive;
+  [KIND]: typeof ServePrimitive;
 };
-interface ServeDescriptorOptions {
+interface ServePrimitiveOptions {
   /**
    * Prefix for the served path.
    *
@@ -27,7 +27,7 @@ interface ServeDescriptorOptions {
    */
   root?: string;
   /**
-   * If true, descriptor will be ignored.
+   * If true, primitive will be ignored.
    *
    * @default false
    */
@@ -50,7 +50,7 @@ interface ServeDescriptorOptions {
    */
   historyApiFallback?: boolean;
   /**
-   * Optional name of the descriptor.
+   * Optional name of the primitive.
    * This is used for logging and debugging purposes.
    *
    * @default Key name.
@@ -83,7 +83,7 @@ interface CacheControlOptions {
    */
   immutable: boolean;
 }
-declare class ServeDescriptor extends Descriptor<ServeDescriptorOptions> {}
+declare class ServePrimitive extends Primitive<ServePrimitiveOptions> {}
 //#endregion
 //#region src/server-static/providers/ServerStaticProvider.d.ts
 declare class ServerStaticProvider {
@@ -93,18 +93,18 @@ declare class ServerStaticProvider {
   protected readonly fileDetector: FileDetector;
   protected readonly log: alepha_logger0.Logger;
   protected readonly directories: ServeDirectory[];
-  protected readonly configure: alepha1.HookDescriptor<"configure">;
-  createStaticServer(options: ServeDescriptorOptions): Promise<void>;
-  createFileHandler(filepath: string, options: ServeDescriptorOptions): Promise<ServerHandler>;
+  protected readonly configure: alepha1.HookPrimitive<"configure">;
+  createStaticServer(options: ServePrimitiveOptions): Promise<void>;
+  createFileHandler(filepath: string, options: ServePrimitiveOptions): Promise<ServerHandler>;
   protected getCacheFileTypes(): string[];
-  protected getCacheControl(filename: string, options: ServeDescriptorOptions): {
+  protected getCacheControl(filename: string, options: ServePrimitiveOptions): {
     maxAge: number;
     immutable: boolean;
   } | undefined;
   getAllFiles(dir: string, ignoreDotEnvFiles?: boolean): Promise<string[]>;
 }
 interface ServeDirectory {
-  options: ServeDescriptorOptions;
+  options: ServePrimitiveOptions;
   files: string[];
 }
 //#endregion
@@ -117,5 +117,5 @@ interface ServeDirectory {
  */
 declare const AlephaServerStatic: alepha1.Service<alepha1.Module>;
 //#endregion
-export { $serve, AlephaServerStatic, CacheControlOptions, ServeDescriptor, ServeDescriptorOptions, ServeDirectory, ServerStaticProvider };
+export { $serve, AlephaServerStatic, CacheControlOptions, ServeDirectory, ServePrimitive, ServePrimitiveOptions, ServerStaticProvider };
 //# sourceMappingURL=index.d.ts.map

package/dist/server-static/index.js

@@ -1,4 +1,4 @@
-import { $hook, $inject, $module, Alepha, Descriptor, KIND, createDescriptor } from "alepha";
+import { $hook, $inject, $module, Alepha, KIND, Primitive, createPrimitive } from "alepha";
 import { AlephaServer, ServerRouterProvider } from "alepha/server";
 import { createReadStream } from "node:fs";
 import { access, readdir, stat } from "node:fs/promises";
@@ -7,15 +7,15 @@ import { DateTimeProvider } from "alepha/datetime";
 import { FileDetector } from "alepha/file";
 import { $logger } from "alepha/logger";
 
-//#region src/server-static/descriptors/$serve.ts
+//#region src/server-static/primitives/$serve.ts
 /**
 * Create a new static file handler.
 */
 const $serve = (options = {}) => {
-	return createDescriptor(ServeDescriptor, options);
+	return createPrimitive(ServePrimitive, options);
 };
-var ServeDescriptor = class extends Descriptor {};
-$serve[KIND] = ServeDescriptor;
+var ServePrimitive = class extends Primitive {};
+$serve[KIND] = ServePrimitive;
 
 //#endregion
 //#region src/server-static/providers/ServerStaticProvider.ts
@@ -29,7 +29,7 @@ var ServerStaticProvider = class {
 	configure = $hook({
 		on: "configure",
 		handler: async () => {
-			await Promise.all(this.alepha.descriptors($serve).map((it) => this.createStaticServer(it.options)));
+			await Promise.all(this.alepha.primitives($serve).map((it) => this.createStaticServer(it.options)));
 		}
 	});
 	async createStaticServer(options) {
@@ -158,10 +158,10 @@ var ServerStaticProvider = class {
 */
 const AlephaServerStatic = $module({
 	name: "alepha.server.static",
-	descriptors: [$serve],
+	primitives: [$serve],
 	services: [AlephaServer, ServerStaticProvider]
 });
 
 //#endregion
-export { $serve, AlephaServerStatic, ServeDescriptor, ServerStaticProvider };
+export { $serve, AlephaServerStatic, ServePrimitive, ServerStaticProvider };
 //# sourceMappingURL=index.js.map

package/dist/server-static/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/server-static/descriptors/$serve.ts","../../src/server-static/providers/ServerStaticProvider.ts","../../src/server-static/index.ts"],"sourcesContent":["import { createDescriptor, Descriptor, KIND } from \"alepha\";\nimport type { DurationLike } from \"alepha/datetime\";\n\n/**\n * Create a new static file handler.\n */\nexport const $serve = (\n  options: ServeDescriptorOptions = {},\n): ServeDescriptor => {\n  return createDescriptor(ServeDescriptor, options);\n};\n\nexport interface ServeDescriptorOptions {\n  /**\n   * Prefix for the served path.\n   *\n   * @default \"/\"\n   */\n  path?: string;\n\n  /**\n   * Path to the directory to serve.\n   *\n   * @default process.cwd()\n   */\n  root?: string;\n\n  /**\n   * If true, descriptor will be ignored.\n   *\n   * @default false\n   */\n  disabled?: boolean;\n\n  /**\n   * Whether to keep dot files (e.g. `.gitignore`, `.env`) in the served directory.\n   *\n   * @default true\n   */\n  ignoreDotEnvFiles?: boolean;\n\n  /**\n   * Whether to use the index.html file when the path is a directory.\n   *\n   * @default true\n   */\n  indexFallback?: boolean;\n\n  /**\n   * Force all requests \"not found\" to be served with the index.html file.\n   * This is useful for single-page applications (SPAs) that use client-side only routing.\n   */\n  historyApiFallback?: boolean;\n\n  /**\n   * Optional name of the descriptor.\n   * This is used for logging and debugging purposes.\n   *\n   * @default Key name.\n   */\n  name?: string;\n\n  /**\n   * Whether to use cache control headers.\n   *\n   * @default {}\n   */\n  cacheControl?: Partial<CacheControlOptions> | false;\n}\n\nexport interface CacheControlOptions {\n  /**\n   * Whether to use cache control headers.\n   *\n   * @default [.js, .css]\n   */\n  fileTypes: string[];\n\n  /**\n   * The maximum age of the cache in seconds.\n   *\n   * @default 60 * 60 * 24 * 2 // 2 days\n   */\n  maxAge: DurationLike;\n\n  /**\n   * Whether to use immutable cache control headers.\n   *\n   * @default true\n   */\n  immutable: boolean;\n}\n\nexport class ServeDescriptor extends Descriptor<ServeDescriptorOptions> {}\n\n$serve[KIND] = ServeDescriptor;\n","import { createReadStream } from \"node:fs\";\nimport { access, readdir, stat } from \"node:fs/promises\";\nimport { basename, isAbsolute, join } from \"node:path\";\nimport type { Readable as NodeStream } from \"node:stream\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { DateTimeProvider } from \"alepha/datetime\";\nimport { FileDetector } from \"alepha/file\";\nimport { $logger } from \"alepha/logger\";\nimport { type ServerHandler, ServerRouterProvider } from \"alepha/server\";\nimport { $serve, type ServeDescriptorOptions } from \"../descriptors/$serve.ts\";\n\nexport class ServerStaticProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly routerProvider = $inject(ServerRouterProvider);\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly log = $logger();\n  protected readonly directories: ServeDirectory[] = [];\n\n  protected readonly configure = $hook({\n    on: \"configure\",\n    handler: async () => {\n      await Promise.all(\n        this.alepha\n          .descriptors($serve)\n          .map((it) => this.createStaticServer(it.options)),\n      );\n    },\n  });\n\n  public async createStaticServer(\n    options: ServeDescriptorOptions,\n  ): Promise<void> {\n    const prefix = options.path ?? \"/\";\n\n    let root = options.root ?? process.cwd();\n    if (!isAbsolute(root)) {\n      root = join(process.cwd(), root);\n    }\n\n    this.log.debug(\"Serve static files\", { prefix, root });\n\n    await stat(root);\n\n    // 1. get all files in the root directory (recursively)\n    const files = await this.getAllFiles(root, options.ignoreDotEnvFiles);\n\n    // 2. create a $route for each file (yes, this could be a lot of routes)\n    const routes = await Promise.all(\n      files.map(async (file) => {\n        const path = file.replace(root, \"\").replace(/\\\\/g, \"/\");\n        this.log.trace(`Mount ${join(prefix, path)} -> ${join(root, path)}`);\n        return {\n          path: join(prefix, encodeURI(path)),\n          handler: await this.createFileHandler(join(root, path), options),\n        };\n      }),\n    );\n\n    for (const route of routes) {\n      this.routerProvider.createRoute(route);\n\n      // if route is for index.html, also create a route without it\n      // e.g. /my/path/index.html -> /my/path/\n      if (\n        options.indexFallback !== false &&\n        route.path.endsWith(\"index.html\")\n      ) {\n        this.routerProvider.createRoute({\n          path: route.path.replace(/index\\.html$/, \"\"),\n          handler: route.handler,\n        });\n      }\n    }\n\n    // 3. store the directory info for reference\n    this.directories.push({\n      options,\n      files: files.map((file) => file.replace(root, \"\").replace(/\\\\/g, \"/\")),\n    });\n\n    // bonus! for SPAs, handle history API fallback\n    if (options.historyApiFallback) {\n      // meaning all unmatched routes should serve index.html\n      this.routerProvider.createRoute({\n        path: join(prefix, \"*\").replace(/\\\\/g, \"/\"),\n        handler: async (request) => {\n          const { reply } = request;\n\n          if (request.url.pathname.includes(\".\")) {\n            // If the request is for a file (e.g., /style.css), do not fall back\n            reply.headers[\"content-type\"] = \"text/plain\";\n            reply.body = \"Not Found\";\n            reply.status = 404;\n            return;\n          }\n\n          reply.headers[\"content-type\"] = \"text/html\";\n          reply.status = 200;\n\n          // Serve index.html for all unmatched routes\n          return createReadStream(join(root, \"index.html\"));\n        },\n      });\n    }\n  }\n\n  public async createFileHandler(\n    filepath: string,\n    options: ServeDescriptorOptions,\n  ): Promise<ServerHandler> {\n    const filename = basename(filepath);\n\n    const hasGzip = await access(`${filepath}.gz`)\n      .then(() => true)\n      .catch(() => false);\n\n    const hasBr = await access(`${filepath}.br`)\n      .then(() => true)\n      .catch(() => false);\n\n    const fileStat = await stat(filepath);\n    const lastModified = fileStat.mtime.toUTCString();\n    const etag = `\"${fileStat.size}-${fileStat.mtime.getTime()}\"`;\n    const contentType = this.fileDetector.getContentType(filename);\n    const cacheControl = this.getCacheControl(filename, options);\n\n    return async (request): Promise<NodeStream | undefined> => {\n      const { headers, reply } = request;\n      let path = filepath;\n\n      const encoding = headers[\"accept-encoding\"];\n      if (encoding) {\n        if (hasBr && encoding.includes(\"br\")) {\n          reply.headers[\"content-encoding\"] = \"br\";\n          path += \".br\";\n        } else if (hasGzip && encoding.includes(\"gzip\")) {\n          reply.headers[\"content-encoding\"] = \"gzip\";\n          path += \".gz\";\n        }\n      }\n\n      reply.headers[\"content-type\"] = contentType;\n      reply.headers[\"accept-ranges\"] = \"bytes\";\n      reply.headers[\"last-modified\"] = lastModified;\n\n      if (cacheControl) {\n        reply.headers[\"cache-control\"] =\n          `public, max-age=${cacheControl.maxAge}`;\n        if (cacheControl.immutable) {\n          reply.headers[\"cache-control\"] += \", immutable\";\n        }\n      }\n\n      reply.headers.etag = etag;\n      if (\n        headers[\"if-none-match\"] === etag ||\n        headers[\"if-modified-since\"] === lastModified\n      ) {\n        reply.status = 304;\n        return;\n      }\n\n      return createReadStream(path);\n    };\n  }\n\n  protected getCacheFileTypes(): string[] {\n    return [\n      \".js\",\n      \".css\",\n      \".woff\",\n      \".woff2\",\n      \".ttf\",\n      \".eot\",\n      \".otf\",\n      \".jpg\",\n      \".jpeg\",\n      \".png\",\n      \".svg\",\n      \".gif\",\n    ];\n  }\n\n  protected getCacheControl(\n    filename: string,\n    options: ServeDescriptorOptions,\n  ): { maxAge: number; immutable: boolean } | undefined {\n    if (!options.cacheControl) {\n      return;\n    }\n\n    const fileTypes =\n      options.cacheControl.fileTypes ?? this.getCacheFileTypes();\n\n    for (const type of fileTypes) {\n      if (filename.endsWith(type)) {\n        return {\n          immutable: options.cacheControl.immutable ?? true,\n          maxAge: this.dateTimeProvider\n            .duration(options.cacheControl.maxAge ?? [30, \"days\"])\n            .as(\"seconds\"),\n        };\n      }\n    }\n  }\n\n  public async getAllFiles(\n    dir: string,\n    ignoreDotEnvFiles = true,\n  ): Promise<string[]> {\n    const entries = await readdir(dir, { withFileTypes: true });\n\n    const files = await Promise.all(\n      entries.map((dirent) => {\n        // skip .env & other dot files\n        if (ignoreDotEnvFiles && dirent.name.startsWith(\".\")) {\n          return [];\n        }\n\n        const fullPath = join(dir, dirent.name);\n        return dirent.isDirectory() ? this.getAllFiles(fullPath) : fullPath;\n      }),\n    );\n\n    return files.flat();\n  }\n}\n\nexport interface ServeDirectory {\n  options: ServeDescriptorOptions;\n  files: string[];\n}\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $serve } from \"./descriptors/$serve.ts\";\nimport { ServerStaticProvider } from \"./providers/ServerStaticProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$serve.ts\";\nexport * from \"./providers/ServerStaticProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Create static file server with `$static()`.\n *\n * @see {@link ServerStaticProvider}\n * @module alepha.server.static\n */\nexport const AlephaServerStatic = $module({\n  name: \"alepha.server.static\",\n  descriptors: [$serve],\n  services: [AlephaServer, ServerStaticProvider],\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/server-static/primitives/$serve.ts","../../src/server-static/providers/ServerStaticProvider.ts","../../src/server-static/index.ts"],"sourcesContent":["import { createPrimitive, KIND, Primitive } from \"alepha\";\nimport type { DurationLike } from \"alepha/datetime\";\n\n/**\n * Create a new static file handler.\n */\nexport const $serve = (options: ServePrimitiveOptions = {}): ServePrimitive => {\n  return createPrimitive(ServePrimitive, options);\n};\n\nexport interface ServePrimitiveOptions {\n  /**\n   * Prefix for the served path.\n   *\n   * @default \"/\"\n   */\n  path?: string;\n\n  /**\n   * Path to the directory to serve.\n   *\n   * @default process.cwd()\n   */\n  root?: string;\n\n  /**\n   * If true, primitive will be ignored.\n   *\n   * @default false\n   */\n  disabled?: boolean;\n\n  /**\n   * Whether to keep dot files (e.g. `.gitignore`, `.env`) in the served directory.\n   *\n   * @default true\n   */\n  ignoreDotEnvFiles?: boolean;\n\n  /**\n   * Whether to use the index.html file when the path is a directory.\n   *\n   * @default true\n   */\n  indexFallback?: boolean;\n\n  /**\n   * Force all requests \"not found\" to be served with the index.html file.\n   * This is useful for single-page applications (SPAs) that use client-side only routing.\n   */\n  historyApiFallback?: boolean;\n\n  /**\n   * Optional name of the primitive.\n   * This is used for logging and debugging purposes.\n   *\n   * @default Key name.\n   */\n  name?: string;\n\n  /**\n   * Whether to use cache control headers.\n   *\n   * @default {}\n   */\n  cacheControl?: Partial<CacheControlOptions> | false;\n}\n\nexport interface CacheControlOptions {\n  /**\n   * Whether to use cache control headers.\n   *\n   * @default [.js, .css]\n   */\n  fileTypes: string[];\n\n  /**\n   * The maximum age of the cache in seconds.\n   *\n   * @default 60 * 60 * 24 * 2 // 2 days\n   */\n  maxAge: DurationLike;\n\n  /**\n   * Whether to use immutable cache control headers.\n   *\n   * @default true\n   */\n  immutable: boolean;\n}\n\nexport class ServePrimitive extends Primitive<ServePrimitiveOptions> {}\n\n$serve[KIND] = ServePrimitive;\n","import { createReadStream } from \"node:fs\";\nimport { access, readdir, stat } from \"node:fs/promises\";\nimport { basename, isAbsolute, join } from \"node:path\";\nimport type { Readable as NodeStream } from \"node:stream\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { DateTimeProvider } from \"alepha/datetime\";\nimport { FileDetector } from \"alepha/file\";\nimport { $logger } from \"alepha/logger\";\nimport { type ServerHandler, ServerRouterProvider } from \"alepha/server\";\nimport { $serve, type ServePrimitiveOptions } from \"../primitives/$serve.ts\";\n\nexport class ServerStaticProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly routerProvider = $inject(ServerRouterProvider);\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly log = $logger();\n  protected readonly directories: ServeDirectory[] = [];\n\n  protected readonly configure = $hook({\n    on: \"configure\",\n    handler: async () => {\n      await Promise.all(\n        this.alepha\n          .primitives($serve)\n          .map((it) => this.createStaticServer(it.options)),\n      );\n    },\n  });\n\n  public async createStaticServer(\n    options: ServePrimitiveOptions,\n  ): Promise<void> {\n    const prefix = options.path ?? \"/\";\n\n    let root = options.root ?? process.cwd();\n    if (!isAbsolute(root)) {\n      root = join(process.cwd(), root);\n    }\n\n    this.log.debug(\"Serve static files\", { prefix, root });\n\n    await stat(root);\n\n    // 1. get all files in the root directory (recursively)\n    const files = await this.getAllFiles(root, options.ignoreDotEnvFiles);\n\n    // 2. create a $route for each file (yes, this could be a lot of routes)\n    const routes = await Promise.all(\n      files.map(async (file) => {\n        const path = file.replace(root, \"\").replace(/\\\\/g, \"/\");\n        this.log.trace(`Mount ${join(prefix, path)} -> ${join(root, path)}`);\n        return {\n          path: join(prefix, encodeURI(path)),\n          handler: await this.createFileHandler(join(root, path), options),\n        };\n      }),\n    );\n\n    for (const route of routes) {\n      this.routerProvider.createRoute(route);\n\n      // if route is for index.html, also create a route without it\n      // e.g. /my/path/index.html -> /my/path/\n      if (\n        options.indexFallback !== false &&\n        route.path.endsWith(\"index.html\")\n      ) {\n        this.routerProvider.createRoute({\n          path: route.path.replace(/index\\.html$/, \"\"),\n          handler: route.handler,\n        });\n      }\n    }\n\n    // 3. store the directory info for reference\n    this.directories.push({\n      options,\n      files: files.map((file) => file.replace(root, \"\").replace(/\\\\/g, \"/\")),\n    });\n\n    // bonus! for SPAs, handle history API fallback\n    if (options.historyApiFallback) {\n      // meaning all unmatched routes should serve index.html\n      this.routerProvider.createRoute({\n        path: join(prefix, \"*\").replace(/\\\\/g, \"/\"),\n        handler: async (request) => {\n          const { reply } = request;\n\n          if (request.url.pathname.includes(\".\")) {\n            // If the request is for a file (e.g., /style.css), do not fall back\n            reply.headers[\"content-type\"] = \"text/plain\";\n            reply.body = \"Not Found\";\n            reply.status = 404;\n            return;\n          }\n\n          reply.headers[\"content-type\"] = \"text/html\";\n          reply.status = 200;\n\n          // Serve index.html for all unmatched routes\n          return createReadStream(join(root, \"index.html\"));\n        },\n      });\n    }\n  }\n\n  public async createFileHandler(\n    filepath: string,\n    options: ServePrimitiveOptions,\n  ): Promise<ServerHandler> {\n    const filename = basename(filepath);\n\n    const hasGzip = await access(`${filepath}.gz`)\n      .then(() => true)\n      .catch(() => false);\n\n    const hasBr = await access(`${filepath}.br`)\n      .then(() => true)\n      .catch(() => false);\n\n    const fileStat = await stat(filepath);\n    const lastModified = fileStat.mtime.toUTCString();\n    const etag = `\"${fileStat.size}-${fileStat.mtime.getTime()}\"`;\n    const contentType = this.fileDetector.getContentType(filename);\n    const cacheControl = this.getCacheControl(filename, options);\n\n    return async (request): Promise<NodeStream | undefined> => {\n      const { headers, reply } = request;\n      let path = filepath;\n\n      const encoding = headers[\"accept-encoding\"];\n      if (encoding) {\n        if (hasBr && encoding.includes(\"br\")) {\n          reply.headers[\"content-encoding\"] = \"br\";\n          path += \".br\";\n        } else if (hasGzip && encoding.includes(\"gzip\")) {\n          reply.headers[\"content-encoding\"] = \"gzip\";\n          path += \".gz\";\n        }\n      }\n\n      reply.headers[\"content-type\"] = contentType;\n      reply.headers[\"accept-ranges\"] = \"bytes\";\n      reply.headers[\"last-modified\"] = lastModified;\n\n      if (cacheControl) {\n        reply.headers[\"cache-control\"] =\n          `public, max-age=${cacheControl.maxAge}`;\n        if (cacheControl.immutable) {\n          reply.headers[\"cache-control\"] += \", immutable\";\n        }\n      }\n\n      reply.headers.etag = etag;\n      if (\n        headers[\"if-none-match\"] === etag ||\n        headers[\"if-modified-since\"] === lastModified\n      ) {\n        reply.status = 304;\n        return;\n      }\n\n      return createReadStream(path);\n    };\n  }\n\n  protected getCacheFileTypes(): string[] {\n    return [\n      \".js\",\n      \".css\",\n      \".woff\",\n      \".woff2\",\n      \".ttf\",\n      \".eot\",\n      \".otf\",\n      \".jpg\",\n      \".jpeg\",\n      \".png\",\n      \".svg\",\n      \".gif\",\n    ];\n  }\n\n  protected getCacheControl(\n    filename: string,\n    options: ServePrimitiveOptions,\n  ): { maxAge: number; immutable: boolean } | undefined {\n    if (!options.cacheControl) {\n      return;\n    }\n\n    const fileTypes =\n      options.cacheControl.fileTypes ?? this.getCacheFileTypes();\n\n    for (const type of fileTypes) {\n      if (filename.endsWith(type)) {\n        return {\n          immutable: options.cacheControl.immutable ?? true,\n          maxAge: this.dateTimeProvider\n            .duration(options.cacheControl.maxAge ?? [30, \"days\"])\n            .as(\"seconds\"),\n        };\n      }\n    }\n  }\n\n  public async getAllFiles(\n    dir: string,\n    ignoreDotEnvFiles = true,\n  ): Promise<string[]> {\n    const entries = await readdir(dir, { withFileTypes: true });\n\n    const files = await Promise.all(\n      entries.map((dirent) => {\n        // skip .env & other dot files\n        if (ignoreDotEnvFiles && dirent.name.startsWith(\".\")) {\n          return [];\n        }\n\n        const fullPath = join(dir, dirent.name);\n        return dirent.isDirectory() ? this.getAllFiles(fullPath) : fullPath;\n      }),\n    );\n\n    return files.flat();\n  }\n}\n\nexport interface ServeDirectory {\n  options: ServePrimitiveOptions;\n  files: string[];\n}\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $serve } from \"./primitives/$serve.ts\";\nimport { ServerStaticProvider } from \"./providers/ServerStaticProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$serve.ts\";\nexport * from \"./providers/ServerStaticProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Create static file server with `$static()`.\n *\n * @see {@link ServerStaticProvider}\n * @module alepha.server.static\n */\nexport const AlephaServerStatic = $module({\n  name: \"alepha.server.static\",\n  primitives: [$serve],\n  services: [AlephaServer, ServerStaticProvider],\n});\n"],"mappings":"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"}