alepha 0.19.4 → 0.19.5

package/src/react/i18n/providers/I18nProvider.ts

@@ -42,7 +42,6 @@ export class I18nProvider<
     for (const item of this.registry) {
       languages.add(item.lang);
     }
-    languages.add(this.options.fallbackLang);
 
     return Array.from(languages);
   }
@@ -70,10 +69,7 @@ export class I18nProvider<
         }
 
         for (const item of this.registry) {
-          if (
-            item.lang === this.lang ||
-            item.lang === this.options.fallbackLang
-          ) {
+          if (item.lang === this.lang || item.lang === this.fallbackLang) {
             this.log.trace("Loading language", {
               lang: item.lang,
               name: item.name,
@@ -139,11 +135,17 @@ export class I18nProvider<
     },
   });
 
+  public get fallbackLang(): string {
+    const configured = this.options.fallbackLang;
+    const hasDict = this.registry.some((item) => item.lang === configured);
+    if (hasDict) {
+      return configured;
+    }
+    return this.registry[0]?.lang ?? configured;
+  }
+
   public get lang(): string {
-    return (
-      this.alepha.store.get("alepha.react.i18n.lang") ||
-      this.options.fallbackLang
-    );
+    return this.alepha.store.get("alepha.react.i18n.lang") || this.fallbackLang;
   }
 
   public translate = (key: string, args: string[] = []) => {
@@ -156,7 +158,7 @@ export class I18nProvider<
     }
 
     for (const item of this.registry) {
-      if (item.lang === this.options.fallbackLang) {
+      if (item.lang === this.fallbackLang) {
         if (item.translations[key]) {
           return this.render(item.translations[key], args); // append lang for fallback
         }

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

@@ -75,7 +75,9 @@ export interface IssuerSettings {
      */
     expiration?: DurationLike;
 
-    // TODO: expirationIdle (max inactive time before the token is invalidated)
+    // 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.
   };
 
   onCreateSession?: (

package/src/server/auth/index.ts

@@ -7,9 +7,13 @@ import { ServerAuthProvider } from "./providers/ServerAuthProvider.ts";
 
 export * from "./index.shared.ts";
 export * from "./primitives/$auth.ts";
+export * from "./primitives/$authApple.ts";
 export * from "./primitives/$authCredentials.ts";
+export * from "./primitives/$authFacebook.ts";
+export * from "./primitives/$authFranceConnect.ts";
 export * from "./primitives/$authGithub.ts";
 export * from "./primitives/$authGoogle.ts";
+export * from "./primitives/$authMicrosoft.ts";
 export * from "./providers/ServerAuthProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -23,6 +27,9 @@ export * from "./providers/ServerAuthProvider.ts";
  * - Google OAuth integration
  * - GitHub OAuth integration
  * - Apple OAuth integration
+ * - Facebook OAuth integration
+ * - Microsoft Entra ID (Azure AD) integration
+ * - France Connect integration
  * - Cookie-based, SSR-friendly authentication
  * - Token management and refresh
  *

package/src/server/auth/primitives/$auth.ts

@@ -198,6 +198,19 @@ export interface OidcOptions {
   scope?: string;
 
   account?: LinkAccountFn;
+
+  /**
+   * OAuth2 response mode.
+   * Apple requires "form_post" which sends the authorization code via POST body
+   * instead of URL query parameters.
+   */
+  responseMode?: "query" | "fragment" | "form_post";
+
+  /**
+   * Additional parameters to include in the authorization URL.
+   * Useful for provider-specific parameters.
+   */
+  authorizationParameters?: Record<string, string>;
 }
 
 export interface LinkAccountOptions {
@@ -369,11 +382,22 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
   /**
    * Extracts user information from the access token.
    * This is used to create a user account from the access token.
+   *
+   * `externalProfile` carries extra profile fields that cannot be derived from the
+   * ID token or userinfo endpoint — e.g. Apple's `user` form field that is only
+   * delivered once, on first authorization. ID token / userinfo fields take
+   * precedence; externalProfile only fills gaps.
    */
-  public async user(tokens: Tokens): Promise<UserAccount> {
+  public async user(
+    tokens: Tokens,
+    externalProfile?: Record<string, unknown>,
+  ): Promise<UserAccount> {
     try {
       if ("oauth" in this.options) {
-        const profile = await this.options.oauth.userinfo(tokens);
+        const profile = {
+          ...externalProfile,
+          ...(await this.options.oauth.userinfo(tokens)),
+        } as OAuth2Profile;
 
         if (this.options.oauth.account) {
           return this.options.oauth.account({
@@ -386,7 +410,10 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
       }
 
       if ("oidc" in this.options) {
-        const payload = this.getUserFromIdToken(tokens.id_token || "");
+        const payload = {
+          ...externalProfile,
+          ...this.getUserFromIdToken(tokens.id_token || ""),
+        } as OAuth2Profile;
 
         if (this.options.oidc.account) {
           return this.options.oidc.account({
@@ -411,6 +438,13 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
     );
   }
 
+  // Security note: No JWT signature verification here is intentional and safe.
+  // The id_token is received via authorizationCodeGrant() which fetches it over a
+  // back-channel TLS connection directly from the IdP's token endpoint. TLS authenticates
+  // the channel. openid-client/oauth4webapi validates claims (issuer, audience, nonce,
+  // expiry) during the grant. Per OIDC spec, cryptographic signature verification is
+  // not required for back-channel token responses — only for implicit/hybrid flows.
+  // See: openid-client index.d.ts enableNonRepudiationChecks() docs.
   protected getUserFromIdToken(idToken: string): OAuth2Profile {
     try {
       return JSON.parse(

package/src/server/auth/primitives/$authApple.ts

@@ -1,8 +1,118 @@
-import { AlephaError } from "alepha";
+import { $context, AlephaError, t } from "alepha";
+import type { IssuerPrimitive } from "alepha/security";
+import type { OAuth2Profile } from "../providers/ServerAuthProvider.ts";
+import {
+  $auth,
+  type LinkAccountFn,
+  type LinkAccountOptions,
+  type OidcOptions,
+  type WithLinkFn,
+} from "./$auth.ts";
 
 /**
- * TODO: Implement Apple authentication
+ * Already configured Apple authentication primitive.
+ *
+ * Uses OpenID Connect (OIDC) to authenticate users via their Apple accounts.
+ * Upon successful authentication, it links the Apple account to a user session.
+ *
+ * Apple-specific behavior:
+ * - `response_mode=form_post` (required by Apple when requesting `email`/`name`).
+ * - Scope: `name email` (Apple does not support the standard `profile` scope).
+ * - The user's name is only provided on the first authorization, as a `user`
+ *   form field on the POST callback. The framework extracts it and injects
+ *   `given_name` / `family_name` / `name` into the profile before linking.
+ *   Subsequent logins only return `sub` and `email` in the ID token.
+ * - `email_verified` and `is_private_email` are normalized from Apple's
+ *   string ("true"/"false") representation to booleans.
+ *
+ * Client secret:
+ * Apple requires the client secret to be a signed ES256 JWT generated from
+ * your Apple private key, team ID, and key ID. This JWT is valid for up to 6
+ * months; you must rotate it before expiration. Generate it out of band and
+ * set it via `APPLE_CLIENT_SECRET`.
+ *
+ * See: https://developer.apple.com/documentation/accountorganizationaldatasharing/creating-a-client-secret
+ *
+ * Environment Variables:
+ * - `APPLE_CLIENT_ID`: The Service ID obtained from the Apple Developer Console.
+ * - `APPLE_CLIENT_SECRET`: The signed ES256 JWT client secret generated from your
+ *   Apple private key.
  */
-export const $authApple = () => {
-  throw new AlephaError("Apple authentication is not implemented yet.");
+export const $authApple = (
+  realm: IssuerPrimitive & WithLinkFn,
+  options: Partial<OidcOptions> = {},
+) => {
+  const { alepha } = $context();
+
+  const env = alepha.parseEnv(
+    t.object({
+      APPLE_CLIENT_ID: t.optional(
+        t.text({
+          description:
+            "The Service ID obtained from the Apple Developer Console.",
+        }),
+      ),
+      APPLE_CLIENT_SECRET: t.optional(
+        t.text({
+          description:
+            "The signed ES256 JWT client secret generated from your Apple private key.",
+        }),
+      ),
+    }),
+  );
+
+  const disabled = !env.APPLE_CLIENT_ID || !env.APPLE_CLIENT_SECRET;
+
+  const name = "apple";
+
+  const userAccount: LinkAccountFn | undefined =
+    options.account ?? (realm.link ? realm.link(name) : undefined);
+
+  if (!userAccount) {
+    throw new AlephaError(
+      "Authentication requires a link function in the realm primitive.",
+    );
+  }
+
+  const account: LinkAccountFn = async (opts) => {
+    return userAccount(normalizeApplePayload(opts));
+  };
+
+  return $auth({
+    issuer: realm,
+    name,
+    oidc: {
+      issuer: "https://appleid.apple.com",
+      clientId: env.APPLE_CLIENT_ID!,
+      clientSecret: env.APPLE_CLIENT_SECRET,
+      scope: "name email",
+      responseMode: "form_post",
+      ...options,
+      account,
+    },
+    disabled,
+  });
+};
+
+/**
+ * Normalize Apple-specific profile quirks before handing off to the
+ * user-provided link function.
+ *
+ * Why: Apple's ID token non-conformities — `email_verified` and
+ * `is_private_email` are delivered as the strings "true"/"false" rather than
+ * booleans. Normalize so downstream code can rely on standard OIDC shapes.
+ */
+const normalizeApplePayload = (
+  opts: LinkAccountOptions,
+): LinkAccountOptions => {
+  const user: OAuth2Profile = { ...opts.user };
+
+  for (const key of ["email_verified", "is_private_email"] as const) {
+    const raw = user[key] as unknown;
+    if (typeof raw === "string") {
+      user[key] = raw === "true";
+    }
+  }
+
+  return { ...opts, user };
 };

package/src/server/auth/primitives/$authFacebook.ts

@@ -0,0 +1,98 @@
+import { $context, AlephaError, t } from "alepha";
+import type { IssuerPrimitive } from "alepha/security";
+import type { OAuth2Profile } from "../providers/ServerAuthProvider.ts";
+import {
+  $auth,
+  type LinkAccountFn,
+  type OidcOptions,
+  type WithLinkFn,
+} from "./$auth.ts";
+
+/**
+ * Already configured Facebook authentication primitive.
+ *
+ * Uses OAuth2 to authenticate users via their Facebook accounts.
+ * Upon successful authentication, it links the Facebook account to a user session.
+ *
+ * Environment Variables:
+ * - `FACEBOOK_CLIENT_ID`: The App ID obtained from the Meta Developer Console.
+ * - `FACEBOOK_CLIENT_SECRET`: The App Secret obtained from the Meta Developer Console.
+ */
+export const $authFacebook = (
+  realm: IssuerPrimitive & WithLinkFn,
+  options: Partial<OidcOptions> = {},
+) => {
+  const { alepha } = $context();
+
+  const env = alepha.parseEnv(
+    t.object({
+      FACEBOOK_CLIENT_ID: t.optional(
+        t.text({
+          description: "The App ID obtained from the Meta Developer Console.",
+        }),
+      ),
+      FACEBOOK_CLIENT_SECRET: t.optional(
+        t.text({
+          description:
+            "The App Secret obtained from the Meta Developer Console.",
+        }),
+      ),
+    }),
+  );
+
+  const disabled = !env.FACEBOOK_CLIENT_ID || !env.FACEBOOK_CLIENT_SECRET;
+
+  const name = "facebook";
+
+  const account: LinkAccountFn | undefined =
+    options.account ?? (realm.link ? realm.link(name) : undefined);
+
+  if (!account) {
+    throw new AlephaError(
+      "Authentication requires a link function in the realm primitive.",
+    );
+  }
+
+  return $auth({
+    issuer: realm,
+    name,
+    oauth: {
+      clientId: env.FACEBOOK_CLIENT_ID!,
+      clientSecret: env.FACEBOOK_CLIENT_SECRET!,
+      authorization: "https://www.facebook.com/v25.0/dialog/oauth",
+      token: "https://graph.facebook.com/v25.0/oauth/access_token",
+      scope: "email",
+      userinfo: async (tokens) => {
+        const res = await fetch(
+          "https://graph.facebook.com/v25.0/me?fields=id,name,email,picture.width(200).height(200)",
+          {
+            headers: {
+              Authorization: `Bearer ${tokens.access_token}`,
+            },
+          },
+        ).then((res) => res.json());
+
+        const user: OAuth2Profile = {
+          sub: res.id,
+        };
+
+        if (res.email) {
+          user.email = res.email;
+        }
+
+        if (res.name) {
+          user.name = res.name.trim();
+        }
+
+        if (res.picture?.data?.url) {
+          user.picture = res.picture.data.url;
+        }
+
+        return user;
+      },
+      ...options,
+      account,
+    },
+    disabled,
+  });
+};

package/src/server/auth/primitives/$authFranceConnect.ts

@@ -0,0 +1,105 @@
+import { $context, AlephaError, t } from "alepha";
+import type { IssuerPrimitive } from "alepha/security";
+import {
+  $auth,
+  type LinkAccountFn,
+  type OidcOptions,
+  type WithLinkFn,
+} from "./$auth.ts";
+
+/**
+ * Creates an authentication provider primitive for France Connect.
+ *
+ * Uses OpenID Connect (OIDC) to authenticate users via France Connect,
+ * the French government's identity federation system. It provides verified
+ * identity data (name, email, birthdate) sourced directly from government
+ * databases.
+ *
+ * **France Connect-specific behaviour**:
+ * - Scopes use individual claim names (`given_name`, `family_name`) rather
+ *   than the standard grouped `profile` scope.
+ * - The `acr_values=eidas1` authorization parameter is mandatory and is
+ *   included automatically.
+ * - Logout is mandatory in France Connect integrations. Store the `id_token`
+ *   returned at login and pass it to the logout endpoint when the session ends.
+ *
+ * **Environment Variables** (obtain from partenaires.franceconnect.gouv.fr):
+ * - `FRANCECONNECT_CLIENT_ID` — OAuth 2.0 client ID for your France Connect service provider.
+ * - `FRANCECONNECT_CLIENT_SECRET` — OAuth 2.0 client secret for your France Connect service provider.
+ *
+ * @example
+ * ```ts
+ * class AuthProviders {
+ *   franceconnect = $authFranceConnect(this.userRealm);
+ * }
+ * ```
+ */
+export const $authFranceConnect = (
+  realm: IssuerPrimitive & WithLinkFn,
+  options: Partial<OidcOptions> = {},
+) => {
+  const { alepha } = $context();
+
+  const env = alepha.parseEnv(
+    t.object({
+      FRANCECONNECT_CLIENT_ID: t.optional(
+        t.text({
+          description:
+            "The OAuth 2.0 client ID for your France Connect service provider, obtained from partenaires.franceconnect.gouv.fr.",
+        }),
+      ),
+      FRANCECONNECT_CLIENT_SECRET: t.optional(
+        t.text({
+          description:
+            "The OAuth 2.0 client secret for your France Connect service provider, obtained from partenaires.franceconnect.gouv.fr.",
+        }),
+      ),
+    }),
+  );
+
+  const disabled =
+    !env.FRANCECONNECT_CLIENT_ID || !env.FRANCECONNECT_CLIENT_SECRET;
+
+  const name = "franceconnect";
+
+  const account: LinkAccountFn | undefined =
+    options.account ?? (realm.link ? realm.link(name) : undefined);
+
+  if (!account) {
+    throw new AlephaError(
+      "Authentication requires a link function in the realm primitive.",
+    );
+  }
+
+  return $auth({
+    issuer: realm,
+    name,
+    oidc: {
+      /**
+       * France Connect production OIDC issuer.
+       * Discovery: https://oidc.franceconnect.gouv.fr/api/v2/.well-known/openid-configuration
+       *
+       * Note: `oidc.franceconnect.gouv.fr` is standard FranceConnect (eidas1).
+       * `auth.franceconnect.gouv.fr` is FranceConnect+ (eidas2/eidas3).
+       */
+      issuer: "https://oidc.franceconnect.gouv.fr/api/v2",
+      clientId: env.FRANCECONNECT_CLIENT_ID!,
+      clientSecret: env.FRANCECONNECT_CLIENT_SECRET,
+      /**
+       * France Connect requires individual claim names as scopes.
+       * The standard grouped `profile` scope is NOT supported.
+       */
+      scope: "openid given_name family_name email",
+      /**
+       * `acr_values=eidas1` is mandatory for all France Connect integrations.
+       */
+      ...options,
+      authorizationParameters: {
+        acr_values: "eidas1",
+        ...options.authorizationParameters,
+      },
+      account,
+    },
+    disabled,
+  });
+};

package/src/server/auth/primitives/$authGithub.ts

@@ -65,12 +65,13 @@ export const $authGithub = (
       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 headers = {
+          Authorization: `Bearer ${tokens.access_token}`,
+          "User-Agent": "Alepha",
+        };
+        const res = await fetch(`${BASE_URL}/user`, { headers }).then((res) =>
+          res.json(),
+        );
 
         const user: OAuth2Profile = {
           sub: res.id.toString(),
@@ -88,16 +89,21 @@ export const $authGithub = (
           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;
+        // `/user` omits the email if the user's public profile hides it, and
+        // never exposes `verified`. Fetch `/user/emails` to fill in both.
+        const emailsRes = await fetch(`${BASE_URL}/user/emails`, { headers });
+        if (emailsRes.ok) {
+          const emails: Array<{
+            email: string;
+            primary: boolean;
+            verified: boolean;
+          }> = await emailsRes.json();
+          if (!user.email) {
+            user.email = (emails.find((e) => e.primary) ?? emails[0])?.email;
+          }
+          if (user.email) {
+            user.email_verified =
+              emails.find((e) => e.email === user.email)?.verified ?? false;
           }
         }
 

package/src/server/auth/primitives/$authMicrosoft.ts

@@ -0,0 +1,88 @@
+import { $context, AlephaError, t } from "alepha";
+import type { IssuerPrimitive } from "alepha/security";
+import {
+  $auth,
+  type LinkAccountFn,
+  type OidcOptions,
+  type WithLinkFn,
+} from "./$auth.ts";
+
+/**
+ * Already configured Microsoft Entra ID (Azure AD) authentication primitive.
+ *
+ * Uses OpenID Connect (OIDC) to authenticate users via their Microsoft accounts.
+ * Supports personal Microsoft accounts, work/school (Azure AD) accounts, and
+ * multi-tenant applications.
+ *
+ * The tenant ID defaults to `"common"`, which allows all Microsoft account types
+ * (personal, work, school). To restrict to a specific Azure AD tenant, set
+ * `MICROSOFT_TENANT_ID` to your tenant's GUID or domain.
+ *
+ * **Note on multi-tenant issuer validation**: Microsoft's OIDC discovery document
+ * for the `common` endpoint returns `{tenantid}` as a literal placeholder in the
+ * `issuer` field. This is expected behavior for multi-tenant endpoints. The
+ * openid-client library handles this during token validation automatically.
+ *
+ * Environment Variables:
+ * - `MICROSOFT_CLIENT_ID`: The application (client) ID from the Azure Portal.
+ * - `MICROSOFT_CLIENT_SECRET`: The client secret value from the Azure Portal.
+ * - `MICROSOFT_TENANT_ID`: (Optional) Azure AD tenant ID or `"common"` for
+ *   multi-tenant. Defaults to `"common"`.
+ */
+export const $authMicrosoft = (
+  realm: IssuerPrimitive & WithLinkFn,
+  options: Partial<OidcOptions> = {},
+) => {
+  const { alepha } = $context();
+
+  const env = alepha.parseEnv(
+    t.object({
+      MICROSOFT_CLIENT_ID: t.optional(
+        t.text({
+          description:
+            "The application (client) ID obtained from the Azure Portal.",
+        }),
+      ),
+      MICROSOFT_CLIENT_SECRET: t.optional(
+        t.text({
+          description:
+            "The client secret value obtained from the Azure Portal.",
+        }),
+      ),
+      MICROSOFT_TENANT_ID: t.optional(
+        t.text({
+          description:
+            "The Azure AD tenant ID or 'common' for multi-tenant. Defaults to 'common'.",
+        }),
+      ),
+    }),
+  );
+
+  const disabled = !env.MICROSOFT_CLIENT_ID || !env.MICROSOFT_CLIENT_SECRET;
+
+  const tenantId = env.MICROSOFT_TENANT_ID ?? "common";
+
+  const name = "microsoft";
+
+  const account: LinkAccountFn | undefined =
+    options.account ?? (realm.link ? realm.link(name) : undefined);
+
+  if (!account) {
+    throw new AlephaError(
+      "Authentication requires a link function in the realm primitive.",
+    );
+  }
+
+  return $auth({
+    issuer: realm,
+    name,
+    oidc: {
+      issuer: `https://login.microsoftonline.com/${tenantId}/v2.0`,
+      clientId: env.MICROSOFT_CLIENT_ID!,
+      clientSecret: env.MICROSOFT_CLIENT_SECRET,
+      ...options,
+      account,
+    },
+    disabled,
+  });
+};