alepha 0.20.2 → 0.20.4

package/src/react/ui/services/SchemaControl.ts

@@ -0,0 +1,209 @@
+import type { FormModel } from "alepha/react/form";
+
+/**
+ * Schema-bound metadata read by `<Control>` (in `@alepha/ui-registry`) to
+ * configure how a field renders. Place under `$control` on any TypeBox
+ * schema option.
+ *
+ * Two forms:
+ *
+ * 1. **Object** — static configuration baked into the schema:
+ *    ```ts
+ *    t.string({ $control: { password: true, icon: "key" } })
+ *    ```
+ *
+ * 2. **Function** — dynamic, computed from current form state:
+ *    ```ts
+ *    t.string({
+ *      $control: ({ form, value }) => {
+ *        if (form.currentValues.kind !== "advanced") return false; // hide
+ *        return { items: () => fetchOptions(form.currentValues.kind) };
+ *      },
+ *    })
+ *    ```
+ *
+ * The function may return:
+ * - a partial `SchemaControl` to merge with explicit `<Control>` props
+ * - `false` to hide the control entirely
+ * - `undefined` to leave the field as-is
+ */
+export interface SchemaControl {
+  // ── Variant forcing ────────────────────────────────────────────────
+  text?: boolean;
+  area?: boolean;
+  password?: boolean;
+  switch?: boolean;
+  number?: boolean;
+  file?: boolean;
+  date?: boolean;
+  datetime?: boolean;
+  time?: boolean;
+  select?: boolean;
+  combobox?: boolean;
+  segmented?: boolean;
+  slider?: boolean;
+  object?: boolean;
+  array?: boolean;
+
+  // ── Labels / hints ────────────────────────────────────────────────
+  /**
+   * Icon name. The registry control maps this to its icon set
+   * (lucide-react). Pass `null` to suppress the schema-inferred icon.
+   */
+  icon?: string | null;
+  label?: string;
+  description?: string;
+  placeholder?: string;
+  /**
+   * HTML `autocomplete` attribute. Use standard tokens like
+   * `"username"`, `"email"`, `"new-password"`, `"current-password"`,
+   * `"street-address"`, `"address-line1"`, `"address-level2"` (city),
+   * `"postal-code"`, `"country"`, `"cc-number"`, `"cc-exp"`,
+   * `"cc-csc"`, `"cc-name"`, `"tel"`, etc.
+   */
+  autoComplete?: string;
+
+  // ── Data ──────────────────────────────────────────────────────────
+  /**
+   * Static or async option list for select / combobox / multi-select.
+   * Each item is either a bare string (used as both value & label) or a
+   * `{ value, label, description?, tag? }` object.
+   */
+  items?: Array<string | SchemaControlItem> | SchemaControlItemsFn;
+
+  /**
+   * Re-fetch `items` (when async) whenever any of these reference values
+   * change. Useful for cascading selects.
+   */
+  itemsWatch?: unknown[];
+
+  /**
+   * Allow the user to create a new option by typing into a select /
+   * multi-select. Pass `true` for `{ value: query, label: query }`, or a
+   * function returning a custom option built from the query.
+   */
+  createNewEntry?:
+    | boolean
+    | ((query: string) => { value: string; label: string });
+
+  // ── Layout ────────────────────────────────────────────────────────
+  /**
+   * Width slot inside an `<AutoForm>` group. Mapped to a grid column span.
+   * - `100` → full row
+   * - `75`  → 3/4 row
+   * - `66`  → 2/3 row
+   * - `50`  → half
+   * - `33`  → one third (default for plain primitives)
+   * - `25`  → one quarter
+   */
+  width?: 100 | 75 | 66 | 50 | 33 | 25;
+
+  // ── Behavior ─────────────────────────────────────────────────────
+  /**
+   * Render `null` (hide) when truthy. Equivalent to a function `$control`
+   * returning `false`, but available as a static value.
+   */
+  hidden?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+
+  // ── Slots ─────────────────────────────────────────────────────────
+  /**
+   * Render before/after the field. Both receive the resolved input.
+   * Typed loosely — UI layer narrows to `ReactNode`.
+   */
+  top?: unknown;
+  bottom?: unknown;
+
+  // ── File upload ───────────────────────────────────────────────────
+  /**
+   * Render a managed upload control (image preview, multi, drag-drop)
+   * that posts to the file API and stores the resulting file ID(s) in
+   * the form. Pass `true` for defaults or an options object:
+   *
+   * ```ts
+   * $control: { upload: { multi: true, accept: "image/*", maxSize: 5_000_000 } }
+   * ```
+   */
+  upload?:
+    | boolean
+    | {
+        multi?: boolean;
+        accept?: string;
+        maxSize?: number;
+        bucket?: string;
+      };
+
+  // ── Array specifics ───────────────────────────────────────────────
+  arrayProps?: {
+    confirmDelete?: boolean | { title?: string; message?: string };
+    /** Computed label for each tab when an array uses tabs mode. */
+    renderTabName?: (i: number, value: unknown) => string;
+    sortable?: boolean;
+    collapsible?: boolean;
+    /** Force grouped (CreateForm-style) tabs even for short arrays. */
+    forceTabs?: boolean;
+  };
+
+  // ── Open extension ────────────────────────────────────────────────
+  [key: string]: unknown;
+}
+
+export interface SchemaControlItem {
+  value: string | number | boolean;
+  label: string;
+  description?: string;
+  tag?: string;
+}
+
+export type SchemaControlItemsFn = (
+  query: string,
+) =>
+  | Array<string | SchemaControlItem>
+  | Promise<Array<string | SchemaControlItem>>;
+
+/**
+ * Function form of `$control`. Receives the live form model + the current
+ * field value, and returns a partial config (merged with explicit props),
+ * `false` to hide, or `undefined` to leave as-is.
+ */
+export type SchemaControlFn = (context: {
+  form: FormModel<any>;
+  value: unknown;
+}) => Partial<SchemaControl> | false | undefined;
+
+export type SchemaControlOption = SchemaControl | SchemaControlFn;
+
+/**
+ * Resolve a raw `$control` value (object or function) into a concrete
+ * partial config. Returns `null` when the field should be hidden.
+ */
+export const resolveSchemaControl = (
+  raw: unknown,
+  context: { form: FormModel<any>; value: unknown },
+): Partial<SchemaControl> | null => {
+  if (raw == null) return {};
+  if (typeof raw === "function") {
+    const result = (raw as SchemaControlFn)(context);
+    if (result === false) return null;
+    if (!result) return {};
+    if (result.hidden) return null;
+    return result;
+  }
+  if (typeof raw === "object") {
+    const obj = raw as SchemaControl;
+    if (obj.hidden) return null;
+    return obj;
+  }
+  return {};
+};
+
+declare module "typebox" {
+  interface TSchemaOptions {
+    /**
+     * UI metadata read by `<Control>` from `@alepha/ui-registry`. See
+     * {@link SchemaControl}.
+     */
+    $control?: SchemaControlOption;
+  }
+}

package/src/scheduler/providers/CronProvider.ts

@@ -67,7 +67,7 @@ export class CronProvider {
         ? this.cronJobs.find((c) => c.name === name)
         : name;
 
-    if (!cron || !cron.running) {
+    if (!cron?.running) {
       return;
     }
 

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

@@ -39,7 +39,7 @@ export function $basicAuth(options: BasicAuthOptions): Middleware {
 
         const authHeader = request.headers.authorization;
 
-        if (!authHeader || !authHeader.startsWith("Basic ")) {
+        if (!authHeader?.startsWith("Basic ")) {
           sendAuthRequired(request);
           throw new HttpError({
             status: 401,

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

@@ -75,9 +75,12 @@ export interface IssuerSettings {
      */
     expiration?: DurationLike;
 
-    // TODO: expirationIdle (max inactive time before the token is invalidated).
-    // Requires tracking lastUsedAt on session refresh and rejecting tokens
-    // that have been idle longer than the threshold.
+    /**
+     * Idle invalidation is enforced by session-backed realms via
+     * `realmAuthSettings.refreshToken.expirationIdle` (in `alepha/api/users`).
+     * Token-only refresh (no `onRefreshSession`) does not support idle
+     * invalidation — it has no stateful row to track `lastUsedAt`.
+     */
   };
 
   onCreateSession?: (

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

@@ -114,7 +114,7 @@ export class ServerAuthProvider {
       // [feature] support for auth providers with fallback
       if (!request.headers.authorization) {
         for (const provider of this.identities) {
-          if ("fallback" in provider.options && !!provider.options.fallback) {
+          if ("fallback" in provider.options && provider.options.fallback) {
             const token = await provider.options.fallback();
             if (token) {
               request.headers.authorization = `Bearer ${token}`;
@@ -336,10 +336,12 @@ export class ServerAuthProvider {
           parameters.scope = scope;
         }
 
+        // biome-ignore lint/complexity/useOptionalChain: oidc is `false | OidcOptions`; optional chaining doesn't narrow `false`
         if (oidc && oidc.responseMode) {
           parameters.response_mode = oidc.responseMode;
         }
 
+        // biome-ignore lint/complexity/useOptionalChain: oidc is `false | OidcOptions`; optional chaining doesn't narrow `false`
         if (oidc && oidc.authorizationParameters) {
           Object.assign(parameters, oidc.authorizationParameters);
         }
@@ -381,10 +383,12 @@ export class ServerAuthProvider {
         parameters.scope = scope;
       }
 
+      // biome-ignore lint/complexity/useOptionalChain: oidc is `false | OidcOptions`; optional chaining doesn't narrow `false`
       if (oidc && oidc.responseMode) {
         parameters.response_mode = oidc.responseMode;
       }
 
+      // biome-ignore lint/complexity/useOptionalChain: oidc is `false | OidcOptions`; optional chaining doesn't narrow `false`
       if (oidc && oidc.authorizationParameters) {
         Object.assign(parameters, oidc.authorizationParameters);
       }

package/src/server/core/__tests__/ServerRouterProvider-serializationError.spec.ts

@@ -0,0 +1,75 @@
+import { Alepha, t } from "alepha";
+import { describe, it } from "vitest";
+import { $action, ServerProvider } from "../index.ts";
+
+class TestApp {
+  badResponse = $action({
+    schema: {
+      response: t.object({
+        name: t.text(),
+        age: t.integer(),
+      }),
+    },
+    handler: () =>
+      ({
+        // missing required `age` → response codec.encode will throw
+        name: "John",
+        secretToken: "leaked-token-xyz",
+      }) as any,
+  });
+}
+
+describe("ServerRouterProvider - response serialization error", () => {
+  describe("in production mode", () => {
+    it("should not leak validation details or response payload in 500 response", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      await alepha.start();
+      const hostname = alepha.inject(ServerProvider).hostname;
+
+      const response = await fetch(`${hostname}/api/badResponse`);
+      const json = await response.json();
+
+      expect(response.status).toBe(500);
+      expect(json.error).toBe("InternalServerError");
+      expect(json.message).toBe("Internal Server Error");
+
+      // payload from the handler must not leak through the error
+      const dump = JSON.stringify(json);
+      expect(dump).not.toContain("leaked-token-xyz");
+      expect(dump).not.toContain("secretToken");
+
+      await alepha.stop();
+    });
+  });
+
+  describe("in development mode", () => {
+    it("should include explicit validation details in 500 response", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create().with(TestApp);
+
+      await alepha.start();
+      const hostname = alepha.inject(ServerProvider).hostname;
+
+      const response = await fetch(`${hostname}/api/badResponse`);
+      const json = await response.json();
+
+      expect(response.status).toBe(500);
+      expect(json.error).toBe("InternalServerError");
+
+      // dev mode must surface enough context to debug the schema mismatch
+      expect(json.message).not.toBe("Internal Server Error");
+      expect(json.message.toLowerCase()).toMatch(/age|required|expected/);
+
+      // even in dev, the raw handler payload (potential secrets) must not be echoed
+      expect(json.message).not.toContain("leaked-token-xyz");
+
+      await alepha.stop();
+    });
+  });
+});

package/src/server/core/__tests__/ServerRouterProvider-validationError.spec.ts

@@ -0,0 +1,306 @@
+import { Alepha, t } from "alepha";
+import { describe, it } from "vitest";
+import { $route, ServerProvider } from "../index.ts";
+
+class TestApp {
+  createUser = $route({
+    method: "POST",
+    path: "/users",
+    schema: {
+      body: t.object({
+        name: t.text(),
+        age: t.integer(),
+      }),
+    },
+    handler: () => {},
+  });
+
+  getUser = $route({
+    method: "GET",
+    path: "/users/:id",
+    schema: {
+      params: t.object({
+        id: t.integer(),
+      }),
+    },
+    handler: () => {},
+  });
+
+  searchUsers = $route({
+    method: "GET",
+    path: "/users",
+    schema: {
+      query: t.object({
+        limit: t.integer({ minimum: 1, maximum: 100 }),
+      }),
+    },
+    handler: () => {},
+  });
+
+  protectedRoute = $route({
+    method: "GET",
+    path: "/protected",
+    schema: {
+      headers: t.object({
+        "x-api-version": t.integer(),
+      }),
+    },
+    handler: () => {},
+  });
+}
+
+const fetchAndStop = async (
+  alepha: Alepha,
+  build: (hostname: string) => { url: string; init?: RequestInit },
+) => {
+  await alepha.start();
+  const hostname = alepha.inject(ServerProvider).hostname;
+  const { url, init } = build(hostname);
+  const response = await fetch(url, init);
+  const json = await response.json();
+  await alepha.stop();
+  return { response, json };
+};
+
+describe("ServerRouterProvider - request validation error", () => {
+  describe("body validation", () => {
+    it("should expose a wrong-type rejection (expected integer, got string)", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users`,
+        init: {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: "John", age: "not-a-number" }),
+        },
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request body:/);
+      expect(json.message.toLowerCase()).toMatch(/integer|expected/);
+      // path locates the offending field
+      expect(json.details).toBe("/age");
+    });
+
+    it("should expose a missing-field rejection (required property `age`)", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users`,
+        init: {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: "John" }),
+        },
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request body:/);
+      // message must name the missing field
+      expect(json.message).toContain("age");
+      expect(json.message.toLowerCase()).toMatch(/required/);
+    });
+
+    it("should behave identically in development mode", async ({ expect }) => {
+      const alepha = Alepha.create().with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users`,
+        init: {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: "John" }),
+        },
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request body:/);
+      expect(json.message.toLowerCase()).toMatch(/age|required/);
+    });
+  });
+
+  describe("params validation", () => {
+    it("should expose the rejection reason in production", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users/not-a-number`,
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request params:/);
+      expect(json.message.toLowerCase()).toMatch(/integer|number|expected/);
+    });
+  });
+
+  describe("query validation", () => {
+    it("should expose the rejection reason in production", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users?limit=9999`,
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request query:/);
+      expect(json.message.toLowerCase()).toMatch(/maximum|less|<=|100/);
+    });
+  });
+
+  describe("header validation", () => {
+    it("should expose the rejection reason in production", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/protected`,
+        // omit required header
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request header:/);
+      expect(json.message.toLowerCase()).toMatch(/x-api-version|required/);
+    });
+
+    it("should coerce string header values to declared schema types", async ({
+      expect,
+    }) => {
+      const seen: { version?: unknown } = {};
+      class CoerceApp {
+        captured = $route({
+          method: "GET",
+          path: "/coerce",
+          schema: {
+            headers: t.object({
+              "x-api-version": t.integer(),
+            }),
+          },
+          handler: ({ headers }) => {
+            seen.version = headers["x-api-version"];
+          },
+        });
+      }
+
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(CoerceApp);
+
+      await alepha.start();
+      const host = alepha.inject(ServerProvider).hostname;
+      const response = await fetch(`${host}/coerce`, {
+        headers: { "x-api-version": "42" },
+      });
+      await alepha.stop();
+
+      expect([200, 204]).toContain(response.status);
+      expect(seen.version).toBe(42);
+      expect(typeof seen.version).toBe("number");
+    });
+
+    it("should preserve undeclared headers (auth, user-agent, ...)", async ({
+      expect,
+    }) => {
+      const seen: { authorization?: string; userAgent?: string } = {};
+      class PreserveApp {
+        check = $route({
+          method: "GET",
+          path: "/preserve",
+          schema: {
+            headers: t.object({
+              "x-api-version": t.integer(),
+            }),
+          },
+          handler: ({ headers }) => {
+            const all = headers as unknown as Record<string, string>;
+            seen.authorization = all.authorization;
+            seen.userAgent = all["user-agent"];
+          },
+        });
+      }
+
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(PreserveApp);
+
+      await alepha.start();
+      const host = alepha.inject(ServerProvider).hostname;
+      const response = await fetch(`${host}/preserve`, {
+        headers: {
+          "x-api-version": "1",
+          authorization: "Bearer abc.def.ghi",
+          "user-agent": "MyClient/1.0",
+        },
+      });
+      await alepha.stop();
+
+      expect([200, 204]).toContain(response.status);
+      expect(seen.authorization).toBe("Bearer abc.def.ghi");
+      expect(seen.userAgent).toBe("MyClient/1.0");
+    });
+
+    it("should accept schema keys regardless of case (lowercase normalization)", async ({
+      expect,
+    }) => {
+      const seen: { version?: unknown } = {};
+      class CaseApp {
+        // Schema declares keys with mixed case — Node lowercases incoming
+        // header names, so the framework must lowercase schema keys when
+        // matching values.
+        check = $route({
+          method: "GET",
+          path: "/case",
+          schema: {
+            headers: t.object({
+              "X-Api-Version": t.integer(),
+            }),
+          },
+          handler: ({ headers }) => {
+            seen.version = (headers as Record<string, unknown>)[
+              "x-api-version"
+            ];
+          },
+        });
+      }
+
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(CaseApp);
+
+      await alepha.start();
+      const host = alepha.inject(ServerProvider).hostname;
+      const response = await fetch(`${host}/case`, {
+        headers: { "x-api-version": "7" },
+      });
+      await alepha.stop();
+
+      expect([200, 204]).toContain(response.status);
+      expect(seen.version).toBe(7);
+    });
+  });
+});

package/src/server/core/errors/ValidationError.ts

@@ -1,11 +1,23 @@
+import { TypeBoxError } from "alepha";
 import { HttpError } from "./HttpError.ts";
 
 export class ValidationError extends HttpError {
   constructor(message = "Validation has failed", cause?: unknown) {
+    let fullMessage = message;
+    let details: string | undefined;
+
+    if (cause instanceof TypeBoxError) {
+      fullMessage = `${message}: ${cause.cause.message}`;
+      if (cause.cause.instancePath) {
+        details = cause.cause.instancePath;
+      }
+    }
+
     super(
       {
-        message,
+        message: fullMessage,
         status: 400,
+        details,
       },
       cause,
     );

package/src/server/core/interfaces/ServerRequest.ts

@@ -212,6 +212,7 @@ export type ResponseKind = "json" | "text" | "void" | "file" | "any";
 
 export type ResponseBodyType =
   // not: object is not allowed, you want object ? add schema !
+  // biome-ignore lint/suspicious/noConfusingVoidType: handlers may return void (no return statement)
   string | Buffer | StreamLike | undefined | null | void;
 
 export type ServerHandler<