@alepha/react 0.12.0 → 0.13.0

package/src/auth/descriptors/$auth.ts

@@ -1,436 +0,0 @@
-import {
-  $inject,
-  AlephaError,
-  type Async,
-  createDescriptor,
-  Descriptor,
-  KIND,
-} from "alepha";
-import { DateTimeProvider } from "alepha/datetime";
-import {
-  type AccessTokenResponse,
-  type RealmDescriptor,
-  SecurityError,
-  SecurityProvider,
-  type UserAccount,
-} from "alepha/security";
-import {
-  allowInsecureRequests,
-  Configuration,
-  discovery,
-  refreshTokenGrant,
-} from "openid-client";
-import type { OAuth2Profile } from "../providers/ReactAuthProvider.ts";
-import type { Tokens } from "../schemas/tokensSchema.ts";
-
-/**
- * Creates an authentication provider descriptor for handling user login flows.
- *
- * Supports multiple authentication strategies: credentials (username/password), OAuth2,
- * and OIDC (OpenID Connect). Handles token management, user profile retrieval, and
- * integration with both external identity providers (Auth0, Keycloak) and internal realms.
- *
- * **Authentication Types**: Credentials, OAuth2 (Google, GitHub), OIDC, External providers
- *
- * @example
- * ```ts
- * class AuthProviders {
- *   // Internal credentials-based auth
- *   credentials = $auth({
- *     realm: this.userRealm,
- *     credentials: {
- *       account: async ({ username, password }) => {
- *         return await this.validateUser(username, password);
- *       }
- *     }
- *   });
- *
- *   // External OIDC provider
- *   keycloak = $auth({
- *     oidc: {
- *       issuer: "https://auth.example.com",
- *       clientId: "my-app",
- *       clientSecret: "secret",
- *       redirectUri: "/auth/callback"
- *     }
- *   });
- * }
- * ```
- */
-export const $auth = (options: AuthDescriptorOptions): AuthDescriptor => {
-  return createDescriptor(AuthDescriptor, options);
-};
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export type AuthDescriptorOptions = {
-  /**
-   * Name of the identity provider.
-   * If not provided, it will be derived from the property key.
-   */
-  name?: string;
-
-  /**
-   * If true, auth provider will be skipped.
-   */
-  disabled?: boolean;
-} & (AuthExternal | AuthInternal);
-
-/**
- * When you let an external service handle authentication. (e.g. Keycloak, Auth0, etc.)
- */
-export type AuthExternal = {
-  /**
-   * Only OIDC is supported for external authentication.
-   */
-  oidc: OidcOptions;
-
-  /**
-   * For anonymous access, this will expect a service account access token.
-   *
-   * ```ts
-   * class App {
-   *   anonymous = $serviceAccount(...);
-   *   auth = $auth({
-   *     // ... config ...
-   *     fallback: this.anonymous,
-   *   })
-   * }
-   * ```
-   */
-  fallback?: () => Async<AccessToken>;
-};
-
-/**
- * When using your own authentication system, e.g. using a database to store user accounts.
- * This is usually used with a custom login form.
- *
- * This relies on the `realm`, which is used to create/verify the access token.
- */
-export type AuthInternal = {
-  realm: RealmDescriptor;
-} & (
-  | {
-      /**
-       * The common username/password authentication.
-       *
-       * - It uses the OAuth2 Client Credentials flow to obtain an access token.
-       *
-       * This is usually used with a custom login form on your website or mobile app.
-       */
-      credentials: CredentialsOptions;
-    }
-  | {
-      /**
-       * OAuth2 authentication. Delegates authentication to an OAuth2 provider. (e.g. Google, GitHub, etc.)
-       *
-       * - It uses the OAuth2 Authorization Code flow to obtain an access token and user information.
-       *
-       * This is usually used with a login button that redirects to the OAuth2 provider.
-       */
-      oauth: OAuth2Options;
-    }
-  | {
-      /**
-       * Like OAuth2, but uses OIDC (OpenID Connect) for authentication and user information retrieval.
-       * OIDC is an identity layer on top of OAuth2, providing user authentication and profile information.
-       *
-       * - It uses the OAuth2 Authorization Code flow to obtain an access token and user information.
-       * - PCKE (Proof Key for Code Exchange) is recommended for security.
-       *
-       * This is usually used with a login button that redirects to the OIDC provider.
-       */
-      oidc: OidcOptions;
-    }
-);
-
-export type CredentialsOptions = {
-  account: (credentials: {
-    username: string;
-    password: string;
-  }) => Async<UserAccount>;
-};
-
-export interface OidcOptions {
-  /**
-   * URL of the OIDC issuer.
-   */
-  issuer: string;
-
-  /**
-   * Client ID for the OIDC client.
-   */
-  clientId: string;
-
-  /**
-   * Client secret for the OIDC client.
-   * Optional if PKCE (Proof Key for Code Exchange) is used.
-   */
-  clientSecret?: string;
-
-  /**
-   * Redirect URI for the OIDC client.
-   * This is where the user will be redirected after authentication.
-   */
-  redirectUri?: string;
-
-  /**
-   * For external auth providers only.
-   * Take the ID token instead of the access token for validation.
-   */
-  useIdToken?: boolean;
-
-  /**
-   * URI to redirect the user after logout.
-   */
-  logoutUri?: string;
-
-  /**
-   * Optional scope for the OIDC client.
-   * @default "openid profile email".
-   */
-  scope?: string;
-
-  account?: (tokens: {
-    access_token: string;
-    user: OAuth2Profile;
-    id_token?: string;
-    expires_in?: number;
-    scope?: string;
-  }) => Async<UserAccount>;
-}
-
-export interface OAuth2Options {
-  /**
-   * URL of the OAuth2 authorization endpoint.
-   */
-  clientId: string;
-
-  /**
-   * Client secret for the OAuth2 client.
-   */
-  clientSecret: string;
-
-  /**
-   * URL of the OAuth2 authorization endpoint.
-   */
-  authorization: string;
-
-  /**
-   * URL of the OAuth2 token endpoint.
-   */
-  token: string;
-
-  /**
-   * Function to retrieve user profile information from the OAuth2 tokens.
-   */
-  userinfo: (tokens: Tokens) => Async<OAuth2Profile>;
-
-  account?: (tokens: {
-    access_token: string;
-    user: OAuth2Profile;
-    id_token?: string;
-    expires_in?: number;
-    scope?: string;
-  }) => Async<UserAccount>;
-
-  /**
-   * URL of the OAuth2 authorization endpoint.
-   */
-  redirectUri?: string;
-
-  /**
-   * URL of the OAuth2 authorization endpoint.
-   */
-  scope?: string;
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export class AuthDescriptor extends Descriptor<AuthDescriptorOptions> {
-  protected readonly securityProvider = $inject(SecurityProvider);
-  protected readonly dateTimeProvider = $inject(DateTimeProvider);
-
-  public oauth?: Configuration;
-
-  public get name() {
-    return this.options.name ?? this.config.propertyKey;
-  }
-
-  public get jwks_uri(): string {
-    const jwks = this.oauth?.serverMetadata().jwks_uri;
-    if (!jwks) {
-      throw new AlephaError("No JWKS URI available for the auth provider");
-    }
-    return jwks;
-  }
-
-  public get scope(): string | undefined {
-    if ("oauth" in this.options) {
-      return this.options.oauth.scope;
-    }
-    if ("oidc" in this.options) {
-      return this.options.oidc.scope || "openid profile email";
-    }
-    throw new AlephaError(
-      "No OAuth2 or OIDC configuration available for the auth provider",
-    );
-  }
-
-  public get redirect_uri() {
-    if ("oauth" in this.options) {
-      return this.options.oauth.redirectUri;
-    }
-    if ("oidc" in this.options) {
-      return this.options.oidc.redirectUri;
-    }
-    throw new AlephaError(
-      "No OAuth2 or OIDC configuration available for the auth provider",
-    );
-  }
-
-  /**
-   * Refreshes the access token using the refresh token.
-   * Can be used on oauth2, oidc or credentials auth providers.
-   */
-  public async refresh(
-    refreshToken: string,
-    accessToken?: string,
-  ): Promise<AccessTokenResponse> {
-    if ("realm" in this.options) {
-      return this.options.realm
-        .refreshToken(refreshToken, accessToken)
-        .then((it) => it.tokens)
-        .catch((error) => {
-          throw new SecurityError(
-            "Failed to refresh access token using the refresh token (realm)",
-            {
-              cause: error,
-            },
-          );
-        });
-    } else if (this.oauth) {
-      try {
-        return {
-          ...(await refreshTokenGrant(this.oauth, refreshToken)),
-          issued_at: this.dateTimeProvider.now().unix(),
-        };
-      } catch (error) {
-        throw new SecurityError(
-          "Failed to refresh access token using the refresh token (oauth2)",
-          {
-            cause: error,
-          },
-        );
-      }
-    }
-
-    throw new AlephaError(
-      "No realm or OAuth2 configuration available for refreshing the access token",
-    );
-  }
-
-  /**
-   * Extracts user information from the access token.
-   * This is used to create a user account from the access token.
-   */
-  public async user(tokens: Tokens): Promise<UserAccount> {
-    try {
-      if ("oauth" in this.options) {
-        const profile = await this.options.oauth.userinfo(tokens);
-
-        if (this.options.oauth.account) {
-          return this.options.oauth.account({
-            ...tokens,
-            user: profile,
-          });
-        }
-
-        return this.securityProvider.createUserFromPayload(profile);
-      }
-
-      if ("oidc" in this.options) {
-        const payload = this.getUserFromIdToken(tokens.id_token || "");
-
-        if (this.options.oidc.account) {
-          return this.options.oidc.account({
-            ...tokens,
-            user: payload,
-          });
-        }
-
-        return this.securityProvider.createUserFromPayload(payload);
-      }
-    } catch (error) {
-      throw new SecurityError(
-        "Failed to extract user from identity provider tokens",
-        {
-          cause: error,
-        },
-      );
-    }
-
-    throw new AlephaError(
-      "This authentication does not support user extraction from tokens",
-    );
-  }
-
-  protected getUserFromIdToken(idToken: string): OAuth2Profile {
-    try {
-      return JSON.parse(
-        Buffer.from(idToken.split(".")[1], "base64").toString("utf8"),
-      ) as OAuth2Profile;
-    } catch (error) {
-      throw new AlephaError("Failed to parse ID Token payload", {
-        cause: error,
-      });
-    }
-  }
-
-  public async prepare() {
-    const addons: Array<(config: Configuration) => void> = [];
-
-    addons.push(allowInsecureRequests);
-
-    if ("oidc" in this.options) {
-      const { oidc } = this.options;
-
-      this.oauth = await discovery(
-        new URL(oidc.issuer),
-        oidc.clientId,
-        {
-          client_secret: oidc.clientSecret,
-        },
-        undefined,
-        {
-          execute: addons,
-        },
-      );
-    }
-
-    if ("oauth" in this.options) {
-      const { oauth } = this.options;
-
-      this.oauth = new Configuration(
-        {
-          authorization_endpoint: oauth.authorization,
-          token_endpoint: oauth.token,
-          issuer: oauth.authorization, // use authorization URL as a pseudo-issuer?
-          // we don't need all of these endpoints
-          jwks_uri: undefined,
-          end_session_endpoint: undefined,
-        },
-        oauth.clientId,
-        {
-          client_secret: oauth.clientSecret,
-        },
-      );
-    }
-  }
-}
-
-$auth[KIND] = AuthDescriptor;
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export type AccessToken = string | { token: () => Async<string> };

package/src/auth/descriptors/$authApple.ts

@@ -1,8 +0,0 @@
-import { AlephaError } from "alepha";
-
-/**
- * TODO: Implement Apple authentication
- */
-export const $authApple = () => {
-  throw new AlephaError("Apple authentication is not implemented yet.");
-};

package/src/auth/descriptors/$authGithub.ts

@@ -1,81 +0,0 @@
-import { $context, t } from "alepha";
-import type { RealmDescriptor } from "alepha/security";
-import type { OAuth2Profile } from "../providers/ReactAuthProvider.ts";
-import { $auth, type OidcOptions } from "./$auth.ts";
-
-/**
- * Already configured GitHub authentication descriptor.
- *
- * Uses OAuth2 to authenticate users via their GitHub accounts.
- * Upon successful authentication, it links the GitHub account to a user session.
- *
- * Environment Variables:
- * - `GITHUB_CLIENT_ID`: The client ID obtained from the GitHub Developer Settings.
- * - `GITHUB_CLIENT_SECRET`: The client secret obtained from the GitHub Developer Settings.
- */
-export const $authGithub = (
-  realm: RealmDescriptor,
-  options: Partial<OidcOptions>,
-) => {
-  const { alepha } = $context();
-
-  const env = alepha.parseEnv(
-    t.object({
-      GITHUB_CLIENT_ID: t.string(),
-      GITHUB_CLIENT_SECRET: t.string(),
-    }),
-  );
-
-  return $auth({
-    realm,
-    name: "github",
-    oauth: {
-      clientId: env.GITHUB_CLIENT_ID,
-      clientSecret: env.GITHUB_CLIENT_SECRET,
-      authorization: "https://github.com/login/oauth/authorize",
-      token: "https://github.com/login/oauth/access_token",
-      scope: "read:user user:email",
-      userinfo: async (tokens) => {
-        const BASE_URL = "https://api.github.com";
-        const res = await fetch(`${BASE_URL}/user`, {
-          headers: {
-            Authorization: `Bearer ${tokens.access_token}`,
-            "User-Agent": "Alepha",
-          },
-        }).then((res) => res.json());
-
-        const user: OAuth2Profile = {
-          sub: res.id.toString(),
-        };
-
-        if (res.email) {
-          user.email = res.email;
-        }
-
-        if (res.name) {
-          user.name = res.name.trim();
-        }
-
-        if (res.avatar_url) {
-          user.picture = res.avatar_url;
-        }
-
-        if (!user.email) {
-          const res = await fetch(`${BASE_URL}/user/emails`, {
-            headers: {
-              Authorization: `Bearer ${tokens.access_token}`,
-              "User-Agent": "Alepha",
-            },
-          });
-          if (res.ok) {
-            const emails: any[] = await res.json();
-            user.email = (emails.find((e) => e.primary) ?? emails[0]).email;
-          }
-        }
-
-        return user;
-      },
-      ...options,
-    },
-  });
-};

package/src/auth/descriptors/$authGoogle.ts

@@ -1,38 +0,0 @@
-import { $context, t } from "alepha";
-import type { RealmDescriptor } from "alepha/security";
-import { $auth, type OidcOptions } from "./$auth.ts";
-
-/**
- * Already configured Google authentication descriptor.
- *
- * Uses OpenID Connect (OIDC) to authenticate users via their Google accounts.
- * Upon successful authentication, it links the Google account to a user session.
- *
- * Environment Variables:
- * - `GOOGLE_CLIENT_ID`: The client ID obtained from the Google Developer Console.
- * - `GOOGLE_CLIENT_SECRET`: The client secret obtained from the Google Developer Console.
- */
-export const $authGoogle = (
-  realm: RealmDescriptor,
-  options: Partial<OidcOptions>,
-) => {
-  const { alepha } = $context();
-
-  const env = alepha.parseEnv(
-    t.object({
-      GOOGLE_CLIENT_ID: t.string(),
-      GOOGLE_CLIENT_SECRET: t.string(),
-    }),
-  );
-
-  return $auth({
-    realm,
-    name: "google",
-    oidc: {
-      issuer: "https://accounts.google.com",
-      clientId: env.GOOGLE_CLIENT_ID,
-      clientSecret: env.GOOGLE_CLIENT_SECRET,
-      ...options,
-    },
-  });
-};

package/src/auth/errors/SessionExpiredError.ts

@@ -1,6 +0,0 @@
-import { AlephaError } from "alepha";
-
-export class SessionExpiredError extends AlephaError {
-  readonly name = "SessionExpiredError";
-  readonly status = 401;
-}

package/src/auth/schemas/tokenResponseSchema.ts

@@ -1,11 +0,0 @@
-import { type Static, t } from "alepha";
-import { userAccountInfoSchema } from "alepha/security";
-import { apiLinksResponseSchema } from "alepha/server/links";
-import { tokensSchema } from "./tokensSchema.ts";
-
-export const tokenResponseSchema = t.extend(tokensSchema, {
-  user: userAccountInfoSchema,
-  api: apiLinksResponseSchema,
-});
-
-export type TokenResponse = Static<typeof tokenResponseSchema>;

package/src/auth/schemas/tokensSchema.ts

@@ -1,21 +0,0 @@
-import type { Static } from "alepha";
-import { t } from "alepha";
-
-export const tokensSchema = t.object({
-  provider: t.text(),
-  access_token: t.text({ size: "rich" }),
-  issued_at: t.number(),
-  expires_in: t.optional(t.number()),
-  refresh_token: t.optional(t.text({ size: "rich" })),
-  refresh_token_expires_in: t.optional(t.number()),
-  refresh_expires_in: t.optional(
-    t.number({
-      description:
-        "Alias of `refresh_token_expires_in` for compatibility with some providers.",
-    }),
-  ),
-  id_token: t.optional(t.text({ size: "rich" })),
-  scope: t.optional(t.text()),
-});
-
-export type Tokens = Static<typeof tokensSchema>;

package/src/auth/schemas/userinfoResponseSchema.ts

@@ -1,10 +0,0 @@
-import { type Static, t } from "alepha";
-import { userAccountInfoSchema } from "alepha/security";
-import { apiLinksResponseSchema } from "alepha/server/links";
-
-export const userinfoResponseSchema = t.object({
-  user: t.optional(userAccountInfoSchema),
-  api: apiLinksResponseSchema,
-});
-
-export type UserinfoResponse = Static<typeof userinfoResponseSchema>;