@mandujs/core 0.53.3 → 0.54.1

package/src/middleware/oauth/providers.ts

@@ -1,115 +1,115 @@
-/**
- * Provider presets for the OAuth middleware.
- *
- * Each factory returns a fresh {@link OAuthProvider} — callers should treat
- * the returned object as immutable, but constructing a new one per `oauth()`
- * invocation means mutations by one consumer never leak across another.
- *
- * Only GitHub and Google ship here. Twitter, Discord, Microsoft etc. are
- * user-contribution territory — the {@link OAuthProvider} shape is stable
- * and narrow on purpose.
- *
- * @module middleware/oauth/providers
- */
-
-import type { OAuthProfile, OAuthProvider } from "./index";
-
-// ========== GitHub ==========
-
-/** Raw shape of `GET https://api.github.com/user`. Fields we consume + passthrough. */
-interface GitHubRawUser {
-  id: number | string;
-  email?: string | null;
-  name?: string | null;
-  avatar_url?: string | null;
-  [key: string]: unknown;
-}
-
-/**
- * GitHub OAuth preset.
- *
- * Docs: https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps
- *
- * Notes:
- *   - The token endpoint defaults to urlencoded responses; the middleware
- *     sets `Accept: application/json` on the POST so we always parse JSON.
- *   - `user:email` scope covers the case where the user's primary email is
- *     private — without it, `raw.email` comes back as `null`.
- *   - PKCE is supported and enabled by default.
- */
-export function github(): OAuthProvider {
-  return {
-    name: "github",
-    authorizationEndpoint: "https://github.com/login/oauth/authorize",
-    tokenEndpoint: "https://github.com/login/oauth/access_token",
-    userinfoEndpoint: "https://api.github.com/user",
-    scopes: ["read:user", "user:email"],
-    pkce: true,
-    normalizeProfile: (raw: unknown): OAuthProfile => {
-      if (!raw || typeof raw !== "object") {
-        throw new Error("[Mandu OAuth/github] userinfo payload is not an object");
-      }
-      const r = raw as GitHubRawUser;
-      if (r.id === undefined || r.id === null) {
-        throw new Error("[Mandu OAuth/github] userinfo payload missing `id`");
-      }
-      return {
-        id: String(r.id),
-        email: typeof r.email === "string" ? r.email : undefined,
-        name: typeof r.name === "string" ? r.name : undefined,
-        avatarUrl: typeof r.avatar_url === "string" ? r.avatar_url : undefined,
-        raw,
-      };
-    },
-  };
-}
-
-// ========== Google ==========
-
-/** Raw shape of Google's OIDC `userinfo` endpoint. */
-interface GoogleRawUser {
-  sub: string;
-  email?: string;
-  name?: string;
-  picture?: string;
-  [key: string]: unknown;
-}
-
-/**
- * Google OAuth preset (OpenID Connect flavor).
- *
- * Docs: https://developers.google.com/identity/protocols/oauth2/openid-connect
- *
- * Notes:
- *   - Uses the static OIDC userinfo endpoint (no discovery at runtime).
- *   - `sub` is the stable provider-scoped user id; `email` may still change
- *     if the user renames their account, so consumers keying user records
- *     should prefer `profile.id` over `profile.email`.
- *   - PKCE is supported and enabled by default.
- */
-export function google(): OAuthProvider {
-  return {
-    name: "google",
-    authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
-    tokenEndpoint: "https://oauth2.googleapis.com/token",
-    userinfoEndpoint: "https://openidconnect.googleapis.com/v1/userinfo",
-    scopes: ["openid", "email", "profile"],
-    pkce: true,
-    normalizeProfile: (raw: unknown): OAuthProfile => {
-      if (!raw || typeof raw !== "object") {
-        throw new Error("[Mandu OAuth/google] userinfo payload is not an object");
-      }
-      const r = raw as GoogleRawUser;
-      if (typeof r.sub !== "string" || r.sub.length === 0) {
-        throw new Error("[Mandu OAuth/google] userinfo payload missing `sub`");
-      }
-      return {
-        id: r.sub,
-        email: typeof r.email === "string" ? r.email : undefined,
-        name: typeof r.name === "string" ? r.name : undefined,
-        avatarUrl: typeof r.picture === "string" ? r.picture : undefined,
-        raw,
-      };
-    },
-  };
-}
+/**
+ * Provider presets for the OAuth middleware.
+ *
+ * Each factory returns a fresh {@link OAuthProvider} — callers should treat
+ * the returned object as immutable, but constructing a new one per `oauth()`
+ * invocation means mutations by one consumer never leak across another.
+ *
+ * Only GitHub and Google ship here. Twitter, Discord, Microsoft etc. are
+ * user-contribution territory — the {@link OAuthProvider} shape is stable
+ * and narrow on purpose.
+ *
+ * @module middleware/oauth/providers
+ */
+
+import type { OAuthProfile, OAuthProvider } from "./index";
+
+// ========== GitHub ==========
+
+/** Raw shape of `GET https://api.github.com/user`. Fields we consume + passthrough. */
+interface GitHubRawUser {
+  id: number | string;
+  email?: string | null;
+  name?: string | null;
+  avatar_url?: string | null;
+  [key: string]: unknown;
+}
+
+/**
+ * GitHub OAuth preset.
+ *
+ * Docs: https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps
+ *
+ * Notes:
+ *   - The token endpoint defaults to urlencoded responses; the middleware
+ *     sets `Accept: application/json` on the POST so we always parse JSON.
+ *   - `user:email` scope covers the case where the user's primary email is
+ *     private — without it, `raw.email` comes back as `null`.
+ *   - PKCE is supported and enabled by default.
+ */
+export function github(): OAuthProvider {
+  return {
+    name: "github",
+    authorizationEndpoint: "https://github.com/login/oauth/authorize",
+    tokenEndpoint: "https://github.com/login/oauth/access_token",
+    userinfoEndpoint: "https://api.github.com/user",
+    scopes: ["read:user", "user:email"],
+    pkce: true,
+    normalizeProfile: (raw: unknown): OAuthProfile => {
+      if (!raw || typeof raw !== "object") {
+        throw new Error("[Mandu OAuth/github] userinfo payload is not an object");
+      }
+      const r = raw as GitHubRawUser;
+      if (r.id === undefined || r.id === null) {
+        throw new Error("[Mandu OAuth/github] userinfo payload missing `id`");
+      }
+      return {
+        id: String(r.id),
+        email: typeof r.email === "string" ? r.email : undefined,
+        name: typeof r.name === "string" ? r.name : undefined,
+        avatarUrl: typeof r.avatar_url === "string" ? r.avatar_url : undefined,
+        raw,
+      };
+    },
+  };
+}
+
+// ========== Google ==========
+
+/** Raw shape of Google's OIDC `userinfo` endpoint. */
+interface GoogleRawUser {
+  sub: string;
+  email?: string;
+  name?: string;
+  picture?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Google OAuth preset (OpenID Connect flavor).
+ *
+ * Docs: https://developers.google.com/identity/protocols/oauth2/openid-connect
+ *
+ * Notes:
+ *   - Uses the static OIDC userinfo endpoint (no discovery at runtime).
+ *   - `sub` is the stable provider-scoped user id; `email` may still change
+ *     if the user renames their account, so consumers keying user records
+ *     should prefer `profile.id` over `profile.email`.
+ *   - PKCE is supported and enabled by default.
+ */
+export function google(): OAuthProvider {
+  return {
+    name: "google",
+    authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenEndpoint: "https://oauth2.googleapis.com/token",
+    userinfoEndpoint: "https://openidconnect.googleapis.com/v1/userinfo",
+    scopes: ["openid", "email", "profile"],
+    pkce: true,
+    normalizeProfile: (raw: unknown): OAuthProfile => {
+      if (!raw || typeof raw !== "object") {
+        throw new Error("[Mandu OAuth/google] userinfo payload is not an object");
+      }
+      const r = raw as GoogleRawUser;
+      if (typeof r.sub !== "string" || r.sub.length === 0) {
+        throw new Error("[Mandu OAuth/google] userinfo payload missing `sub`");
+      }
+      return {
+        id: r.sub,
+        email: typeof r.email === "string" ? r.email : undefined,
+        name: typeof r.name === "string" ? r.name : undefined,
+        avatarUrl: typeof r.picture === "string" ? r.picture : undefined,
+        raw,
+      };
+    },
+  };
+}