alepha 0.15.1 → 0.15.2

package/src/react/auth/__tests__/$auth.spec.ts

@@ -0,0 +1,202 @@
+import { randomUUID } from "node:crypto";
+import { Alepha } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
+import { $issuer, AlephaSecurity } from "alepha/security";
+import { AlephaServer, HttpClient, ServerProvider } from "alepha/server";
+import {
+  $auth,
+  alephaServerAuthRoutes,
+  type TokenResponse,
+  tokenResponseSchema,
+  tokensSchema,
+} from "alepha/server/auth";
+import { $client } from "alepha/server/links";
+import { describe, test } from "vitest";
+import { ReactAuth, type ReactAuthProvider } from "../index.ts";
+
+describe("$auth", () => {
+  const user = {
+    id: randomUUID(),
+    name: "John Doe",
+    username: "john",
+    password: "***",
+    roles: ["admin"],
+  };
+
+  class App {
+    issuer = $issuer({
+      secret: "my-secret-key",
+      roles: [
+        {
+          name: "admin",
+          permissions: [{ name: "*" }],
+        },
+      ],
+    });
+
+    auth = $auth({
+      issuer: this.issuer,
+      credentials: {
+        account: () => user,
+      },
+    });
+
+    api = $client<ReactAuthProvider>();
+  }
+
+  const userinfo = (alepha: Alepha, token?: string) =>
+    alepha
+      .inject(HttpClient)
+      .fetch(
+        `${alepha.inject(ServerProvider).hostname}${alephaServerAuthRoutes.userinfo}`,
+        {
+          method: "GET",
+          headers: {
+            authorization: `Bearer ${token}`,
+          },
+        },
+      )
+      .then((it) => it.data);
+
+  const login = (alepha: Alepha) =>
+    alepha
+      .inject(HttpClient)
+      .fetch(
+        `${alepha.inject(ServerProvider).hostname}${alephaServerAuthRoutes.token}?provider=auth`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            username: user.username,
+            password: user.password,
+          }),
+          schema: {
+            response: tokenResponseSchema,
+          },
+        },
+      );
+
+  const refresh = (alepha: Alepha, tokens: TokenResponse) =>
+    alepha
+      .inject(HttpClient)
+      .fetch(
+        `${alepha.inject(ServerProvider).hostname}${alephaServerAuthRoutes.refresh}?provider=auth`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            refresh_token: tokens.refresh_token!,
+            access_token: tokens.access_token,
+          }),
+          schema: {
+            response: tokensSchema,
+          },
+        },
+      );
+
+  test("should login with credentials", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    const auth = alepha.inject(ReactAuth);
+    await alepha.start();
+
+    expect(auth.user).toBeUndefined();
+    await auth.login("auth", {
+      username: user.username,
+      password: user.password,
+      hostname: alepha.inject(ServerProvider).hostname,
+    });
+    expect(auth.user).toEqual({
+      id: user.id,
+      name: user.name,
+      roles: user.roles,
+      username: user.username,
+    });
+  });
+
+  test("should get userinfo", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    await alepha.start();
+
+    const { data: tokens } = await login(alepha);
+
+    expect(await userinfo(alepha, tokens.access_token)).toEqual({
+      user: {
+        id: user.id,
+        name: user.name,
+        roles: user.roles,
+        username: user.username,
+        sessionId: expect.any(String),
+      },
+      api: {
+        prefix: "/api",
+        links: [],
+      },
+    });
+  });
+
+  test("should reject expired token", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    await alepha.start();
+
+    const { data: tokens } = await login(alepha);
+
+    await alepha.inject(DateTimeProvider).travel(1, "hour");
+
+    expect(await userinfo(alepha, tokens.access_token)).toEqual({
+      api: {
+        prefix: "/api",
+        links: [],
+      },
+    });
+  });
+
+  test("should refresh expired token", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    await alepha.start();
+
+    const { data: tokens } = await login(alepha);
+
+    await alepha.inject(DateTimeProvider).travel(1, "hour");
+
+    const { data: tokens2 } = await refresh(alepha, tokens);
+
+    expect(await userinfo(alepha, tokens2.access_token)).toEqual({
+      user: {
+        id: user.id,
+        name: user.name,
+        roles: user.roles,
+        username: user.username,
+      },
+      api: {
+        prefix: "/api",
+        links: [],
+      },
+    });
+  });
+
+  test("should reject expired refresh token", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    await alepha.start();
+
+    const { data: tokens } = await login(alepha);
+
+    await alepha.inject(DateTimeProvider).travel(40, "days");
+
+    await expect(refresh(alepha, tokens)).rejects.toThrowError(
+      "Failed to refresh access token using the refresh token (issuer)",
+    );
+  });
+});

package/src/react/auth/hooks/useAuth.ts

@@ -0,0 +1,32 @@
+import { useAlepha, useStore } from "alepha/react";
+import { type HttpVirtualClient, LinkProvider } from "alepha/server/links";
+import { ReactAuth } from "../services/ReactAuth.ts";
+
+export const useAuth = <T extends object = any>() => {
+  const alepha = useAlepha();
+  const [user] = useStore("alepha.server.request.user");
+
+  return {
+    user,
+    logout: () => {
+      alepha.inject(ReactAuth).logout();
+    },
+    login: async (
+      provider: keyof T,
+      options: {
+        username?: string;
+        password?: string;
+        redirect?: string;
+        realm?: string;
+        [extra: string]: any;
+      } = {},
+    ) => {
+      await alepha.inject(ReactAuth).login(provider as string, options);
+    },
+    can: <Api extends object = any>(
+      name: keyof HttpVirtualClient<Api>,
+    ): boolean => {
+      return alepha.inject(LinkProvider).can(name as string);
+    },
+  };
+};

package/src/react/auth/index.browser.ts

@@ -0,0 +1,13 @@
+import { $module } from "alepha";
+import { ReactAuth } from "./services/ReactAuth.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./index.shared.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaReactAuth = $module({
+  name: "alepha.react.auth",
+  services: [ReactAuth],
+});

package/src/react/auth/index.shared.ts

@@ -0,0 +1,2 @@
+export * from "./hooks/useAuth.ts";
+export * from "./services/ReactAuth.ts";

package/src/react/auth/index.ts

@@ -0,0 +1,48 @@
+import { $module } from "alepha";
+import { AlephaReact } from "alepha/react";
+import type { UserAccount } from "alepha/security";
+import { $auth, AlephaServerAuth } from "alepha/server/auth";
+import { AlephaServerLinks } from "alepha/server/links";
+import { ReactAuthProvider } from "./providers/ReactAuthProvider.ts";
+import { ReactAuth } from "./services/ReactAuth.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./index.shared.ts";
+export * from "./providers/ReactAuthProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha/react/router" {
+  interface ReactRouterState {
+    user?: UserAccount;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | frontend | rare | stable |
+ *
+ * Auth-related React components and hooks.
+ *
+ * **Features:**
+ * - Login/logout components
+ * - Protected route wrappers
+ * - Auth state hooks
+ *
+ * @module alepha.react.auth
+ */
+export const AlephaReactAuth = $module({
+  name: "alepha.react.auth",
+  primitives: [$auth],
+  services: [
+    AlephaReact,
+    AlephaServerLinks,
+    AlephaServerAuth,
+    ReactAuthProvider,
+    ReactAuth,
+  ],
+});

package/src/react/auth/providers/ReactAuthProvider.ts

@@ -0,0 +1,16 @@
+import { $hook, $inject, Alepha } from "alepha";
+
+export class ReactAuthProvider {
+  protected readonly alepha = $inject(Alepha);
+
+  public readonly onRender = $hook({
+    on: "react:server:render:begin",
+    handler: async ({ request, state }) => {
+      if (request?.user) {
+        const { token, realm, ...user } = request.user; // do not send token and realm to the client
+        this.alepha.store.set("alepha.server.request.user", user); // for hydration, browser, etc...
+        state.user = user;
+      }
+    },
+  });
+}

package/src/react/auth/services/ReactAuth.ts

@@ -0,0 +1,135 @@
+import { $hook, $inject, Alepha } from "alepha";
+import { $logger } from "alepha/logger";
+import { ReactBrowserProvider, Redirection } from "alepha/react/router";
+import type { UserAccountToken } from "alepha/security";
+import { HttpClient } from "alepha/server";
+import {
+  alephaServerAuthRoutes,
+  type Tokens,
+  tokenResponseSchema,
+  userinfoResponseSchema,
+} from "alepha/server/auth";
+import { LinkProvider } from "alepha/server/links";
+
+/**
+ * Browser, SSR friendly, service to handle authentication.
+ */
+export class ReactAuth {
+  protected readonly log = $logger();
+  protected readonly alepha = $inject(Alepha);
+  protected readonly httpClient = $inject(HttpClient);
+  protected readonly linkProvider = $inject(LinkProvider);
+
+  protected readonly onBeginTransition = $hook({
+    on: "react:transition:begin",
+    handler: async (event) => {
+      if (this.alepha.isBrowser()) {
+        Object.defineProperty(event.state, "user", {
+          get: () => this.user,
+        });
+      }
+    },
+  });
+
+  protected readonly onFetchRequest = $hook({
+    on: "client:onRequest",
+    handler: async ({ request }) => {
+      if (this.alepha.isBrowser() && this.user) {
+        // ensure cookies are sent with requests and refresh-able
+        request.credentials ??= "include";
+      }
+    },
+  });
+
+  /**
+   * Get the current authenticated user.
+   *
+   * Alias for `alepha.state.get("user")`
+   */
+  public get user(): UserAccountToken | undefined {
+    return this.alepha.store.get("alepha.server.request.user");
+  }
+
+  public async ping() {
+    const { data } = await this.httpClient.fetch(
+      alephaServerAuthRoutes.userinfo,
+      {
+        schema: { response: userinfoResponseSchema },
+      },
+    );
+
+    this.alepha.store.set("alepha.server.request.apiLinks", data.api);
+    this.alepha.store.set("alepha.server.request.user", data.user);
+
+    return data.user;
+  }
+
+  public can(action: string): boolean {
+    if (!this.user) {
+      return false;
+    }
+
+    return this.linkProvider.can(action);
+  }
+
+  public async login(
+    provider: string,
+    options: {
+      hostname?: string;
+      username?: string;
+      password?: string;
+      redirect?: string;
+      realm?: string;
+      [extra: string]: any;
+    },
+  ): Promise<Tokens> {
+    const realmParam = options.realm
+      ? `&realm=${encodeURIComponent(options.realm)}`
+      : "";
+
+    if (options.username || options.password) {
+      const { data } = await this.httpClient.fetch(
+        `${options.hostname || ""}${alephaServerAuthRoutes.token}?provider=${provider}${realmParam}`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            username: options.username,
+            password: options.password,
+          }),
+          schema: { response: tokenResponseSchema },
+        },
+      );
+
+      this.alepha.store.set("alepha.server.request.apiLinks", data.api);
+      this.alepha.store.set("alepha.server.request.user", data.user);
+
+      return data;
+    }
+
+    if (this.alepha.isBrowser()) {
+      const browser = this.alepha.inject(ReactBrowserProvider);
+      const redirect =
+        options.redirect ||
+        (browser.transitioning
+          ? window.location.origin + browser.transitioning.to
+          : window.location.href);
+
+      const href = `${window.location.origin}${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${encodeURIComponent(redirect)}`;
+
+      if (browser.transitioning) {
+        throw new Redirection(href);
+      } else {
+        window.location.href = href;
+        return {} as Tokens;
+      }
+    }
+
+    throw new Redirection(
+      `${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${options.redirect || "/"}`,
+    );
+  }
+
+  public logout() {
+    window.location.href = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;
+  }
+}

package/src/react/core/__tests__/Router.spec.tsx

@@ -0,0 +1,169 @@
+import { Alepha, t } from "alepha";
+import { renderToString } from "react-dom/server";
+import { test } from "vitest";
+import { NestedView } from "../../router/index.ts";
+import { ReactBrowserRouterProvider } from "../../router/providers/ReactBrowserRouterProvider.ts";
+
+const setup = () => {
+  const alepha = Alepha.create();
+  const router = alepha.inject(ReactBrowserRouterProvider);
+
+  const render = async (path: string): Promise<string> => {
+    await router.transition(new URL(`http://localhost${path}`));
+    const state = alepha.store.get("alepha.react.router.state");
+    if (!state) {
+      throw new Error(
+        "Router state not found. Ensure the router is properly configured.",
+      );
+    }
+    const element = router.root(state);
+    return renderToString(element).replaceAll("<!-- -->", "");
+  };
+
+  return {
+    router,
+    render,
+    alepha,
+  };
+};
+
+test("Router - Basic", async ({ expect }) => {
+  const { router, render, alepha } = setup();
+
+  router.add({
+    name: "Test",
+    path: "/",
+    component: () => "Hey",
+  });
+
+  router.add({
+    name: "NotFound",
+    path: "/*",
+    component: () => "Not Found",
+  });
+
+  await alepha.start();
+
+  expect(await render("/")).toEqual("Hey");
+  expect(await render("/zz")).toEqual("Not Found");
+});
+
+test("Router - NestedView", async ({ expect }) => {
+  const { router, render, alepha } = setup();
+
+  router.add({
+    name: "Test",
+    component: () => (
+      <>
+        ((
+        <NestedView />
+        ))
+      </>
+    ),
+    children: [
+      {
+        name: "Home",
+        path: "/",
+        component: () => "Home",
+      },
+      {
+        name: "Hello",
+        path: "/hello/:name",
+        schema: {
+          params: t.object({
+            name: t.text(),
+          }),
+        },
+        loader: ({ params }) => params,
+        component: (props) => `Hello, ${props.name}!`,
+      },
+    ],
+  });
+
+  await alepha.start();
+
+  expect(await render("/")).toEqual("((Home))");
+  expect(await render("/hello/jack")).toEqual("((Hello, jack!))");
+});
+
+test("Router - All routes", async ({ expect }) => {
+  const { router, render, alepha } = setup();
+
+  router.add({
+    children: [
+      {
+        path: "/*",
+        component: () => "404",
+      },
+      {
+        component: () => "home",
+      },
+      {
+        path: "about",
+        component: () => "about",
+      },
+      {
+        path: "sub",
+        children: [
+          {
+            component: () => "a",
+          },
+          {
+            path: "b",
+            component: () => "b",
+          },
+        ],
+      },
+      {
+        path: "users",
+        component: () => <NestedView>yo</NestedView>,
+        children: [
+          {
+            path: "new",
+            component: () => "users/new",
+          },
+          {
+            path: ":id",
+            schema: { params: t.object({ id: t.text() }) },
+            loader: ({ params }) => {
+              if (params.id === "boom") throw new Error("boom");
+              return params;
+            },
+            children: [
+              {
+                loader: ({ params }) => params,
+                component: ({ id }) => `hey ${id}`,
+              },
+              {
+                path: "profile",
+                loader: ({ params }) => params,
+                component: ({ id }) => `profile of ${id}`,
+              },
+            ],
+          },
+        ],
+        errorHandler: (error) => {
+          return `Error: ${error.message}`;
+        },
+      },
+    ],
+  });
+
+  await alepha.start();
+
+  expect(await render("/")).toEqual("home");
+  expect(await render("/about")).toEqual("about");
+  expect(await render("/noop")).toEqual("404");
+  expect(await render("/noop/noop")).toEqual("404");
+  expect(await render("/sub")).toEqual("a");
+  expect(await render("/sub/")).toEqual("a");
+  expect(await render("/sub/b")).toEqual("b");
+  expect(await render("/sub/noop")).toEqual("404");
+  expect(await render("/users")).toEqual("yo");
+  expect(await render("/users/")).toEqual("yo");
+  expect(await render("/users/a")).toEqual("hey a");
+  expect(await render("/users/boom")).toEqual("Error: boom");
+  expect(await render("/users/new")).toEqual("users/new");
+  expect(await render("/users/hey/ho")).toEqual("404");
+  expect(await render("/users/a/profile")).toEqual("profile of a");
+});

package/src/react/core/components/ClientOnly.tsx

@@ -0,0 +1,49 @@
+import {
+  type PropsWithChildren,
+  type ReactNode,
+  useEffect,
+  useState,
+} from "react";
+
+export interface ClientOnlyProps {
+  fallback?: ReactNode;
+  disabled?: boolean;
+}
+
+/**
+ * A small utility component that renders its children only on the client side.
+ *
+ * Optionally, you can provide a fallback React node that will be rendered.
+ *
+ * You should use this component when
+ * - you have code that relies on browser-specific APIs
+ * - you want to avoid server-side rendering for a specific part of your application
+ * - you want to prevent pre-rendering of a component
+ *
+ * @example
+ * ```tsx
+ * import { ClientOnly } from "alepha/react";
+ *
+ * const MyComponent = () => {
+ *   // Avoids SSR issues with Date API
+ *   return (
+ *     <ClientOnly>
+ *       {new Date().toLocaleTimeString()}
+ *     </ClientOnly>
+ *   );
+ * }
+ * ```
+ */
+const ClientOnly = (props: PropsWithChildren<ClientOnlyProps>) => {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => setMounted(true), []);
+
+  if (props.disabled) {
+    return props.children;
+  }
+
+  return mounted ? props.children : props.fallback;
+};
+
+export default ClientOnly;