@fonderie/auth 7.1.1 → 7.2.0

package/brain/outcomes.md

@@ -129,6 +129,9 @@ Raw SQL ships in `node_modules/@fonderie/auth/dist/migrations/sql/` — read it
 
 | Method | Path | Middleware chain (auth / validation / handler) |
 |---|---|---|
+| GET | `/auth/apple` | `oauth.appleInit` |
+| POST | `/auth/apple/callback` | `oauth.appleCallback` |
+| POST | `/auth/apple/native` | `ipLimit('login') → validate(appleNativeSchema) → oauth.appleNative` |
 | POST | `/auth/email/forgot` | `ipLimit('forgot') → validate(forgotPasswordSchema) → acctLimit('forgot') → auth.forgotPassword` |
 | POST | `/auth/email/reset` | `ipLimit('reset') → validate(resetPasswordSchema) → auth.resetPassword` |
 | GET | `/auth/google` | `oauth.googleInit` |

package/brain/signatures.md

@@ -56,7 +56,7 @@ interface IAuthConfig extends IAuthSecrets, IAuthRuntimeConfig {
     secureCookies?: boolean;
     rateLimit?: IAuthRateLimitConfig | false;
     accessTokenDuration?: string;
-    providers: ('email' | 'phone' | 'google' | 'github')[];
+    providers: ('email' | 'phone' | 'google' | 'github' | 'apple')[];
     appName?: string;
     passwordResetUrl?: string;
     resolve?: (ctx: {
@@ -75,6 +75,14 @@ interface IAuthSecrets {
         clientSecret: string;
         redirectUri: string;
     };
+    apple?: {
+        clientId: string;
+        teamId: string;
+        keyId: string;
+        privateKey: string;
+        redirectUri: string;
+        nativeClientIds?: string[];
+    };
 }
 
 interface IAuthRuntimeConfig {
@@ -145,7 +153,7 @@ interface ISessionDTO {
 
 function validate(schema: IRequestSchema): Middleware
 
-namespace schemas — exports: ChangePasswordInput, LoginInput, RegisterInput, ResetPasswordInput, changePasswordSchema, forgotPasswordSchema, loginSchema, mfaTokenSchema, refreshSchema, registerSchema, resetPasswordSchema, updateEmailSchema, updatePhoneSchema, updatePreferencesSchema, updateProfileSchema, verifySchema
+namespace schemas — exports: ChangePasswordInput, LoginInput, RegisterInput, ResetPasswordInput, appleNativeSchema, changePasswordSchema, forgotPasswordSchema, loginSchema, mfaTokenSchema, refreshSchema, registerSchema, resetPasswordSchema, updateEmailSchema, updatePhoneSchema, updatePreferencesSchema, updateProfileSchema, verifySchema
 
 type RegisterInput = z.infer<typeof registerSchema>;
 

package/dist/index.cjs

@@ -168,6 +168,7 @@ function buildAuthAccountLimiter(route, store, config) {
 // src/schemas.ts
 var schemas_exports = {};
 __export(schemas_exports, {
+  appleNativeSchema: () => appleNativeSchema,
   changePasswordSchema: () => changePasswordSchema,
   forgotPasswordSchema: () => forgotPasswordSchema,
   loginSchema: () => loginSchema,
@@ -199,6 +200,12 @@ var loginSchema = import_zod.z.union([
   import_zod.z.object({ email, password: import_zod.z.string().min(1).max(128) }),
   import_zod.z.object({ phone })
 ]);
+var appleNativeSchema = import_zod.z.object({
+  identityToken: import_zod.z.string().min(1).max(8192),
+  // Optional nonce the app bound to the native request; when present we check
+  // it against the token's `nonce` claim to defend against replay.
+  nonce: import_zod.z.string().max(256).optional()
+});
 var refreshSchema = import_zod.z.object({ refreshToken: import_zod.z.string().min(1).optional() });
 var forgotPasswordSchema = import_zod.z.object({ email });
 var resetPasswordSchema = import_zod.z.union([
@@ -2295,11 +2302,124 @@ function userController(store, config, bus) {
 
 // src/controllers/oauth.controller.ts
 var import_node_crypto7 = require("crypto");
+var import_jsonwebtoken2 = __toESM(require("jsonwebtoken"), 1);
 var import_core8 = require("@fonderie/core");
+var APPLE_AUTH_URL = "https://appleid.apple.com/auth/authorize";
+var APPLE_TOKEN_URL = "https://appleid.apple.com/auth/token";
+var APPLE_KEYS_URL = "https://appleid.apple.com/auth/keys";
+var APPLE_ISSUER = "https://appleid.apple.com";
+function mintAppleClientSecret(apple) {
+  const now = Math.floor(Date.now() / 1e3);
+  return import_jsonwebtoken2.default.sign(
+    { iss: apple.teamId, iat: now, exp: now + 300, aud: APPLE_ISSUER, sub: apple.clientId },
+    apple.privateKey,
+    { algorithm: "ES256", keyid: apple.keyId }
+  );
+}
+var appleKeyCache = null;
+var APPLE_KEYS_TTL_MS = 60 * 60 * 1e3;
+async function getApplePublicKey(kid) {
+  const fresh = appleKeyCache && Date.now() - appleKeyCache.fetchedAt < APPLE_KEYS_TTL_MS;
+  if (!fresh || !appleKeyCache.keys.some((k) => k.kid === kid)) {
+    try {
+      const res = await fetch(APPLE_KEYS_URL);
+      const data = await res.json();
+      if (Array.isArray(data.keys)) appleKeyCache = { keys: data.keys, fetchedAt: Date.now() };
+    } catch {
+    }
+  }
+  const jwk = appleKeyCache?.keys.find((k) => k.kid === kid);
+  if (!jwk) return null;
+  try {
+    return (0, import_node_crypto7.createPublicKey)({ key: jwk, format: "jwk" });
+  } catch {
+    return null;
+  }
+}
+async function verifyAppleIdToken(idToken, opts) {
+  if (opts.audiences.length === 0) return null;
+  const decoded = import_jsonwebtoken2.default.decode(idToken, { complete: true });
+  if (!decoded || typeof decoded === "string") return null;
+  const kid = decoded.header.kid;
+  if (!kid) return null;
+  const key = await getApplePublicKey(kid);
+  if (!key) return null;
+  try {
+    const payload = import_jsonwebtoken2.default.verify(idToken, key, {
+      algorithms: ["RS256"],
+      issuer: APPLE_ISSUER,
+      // jsonwebtoken types `audience` as a non-empty tuple; runtime accepts a
+      // list and matches the token's aud against ANY entry (guarded non-empty
+      // above).
+      audience: opts.audiences
+    });
+    if (opts.nonce !== void 0 && payload.nonce !== opts.nonce) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+var appleEmailVerified = (c) => c.email_verified === true || c.email_verified === "true";
 function oauthController(store, config) {
   const users = new UserModel(store);
   const sessions = new SessionModel(store);
   const loginEvents = new LoginEventModel(store);
+  const completeAppleLogin = async (ctx, claims) => {
+    const meta = requestMeta(ctx);
+    if (!claims.email) {
+      return (0, import_core8.setApiResponse)(import_core8.HTTP.BAD_REQUEST, "APPLE_AUTH_FAILED", "No email in Apple identity token");
+    }
+    if (!claims.emailVerified) {
+      return (0, import_core8.setApiResponse)(import_core8.HTTP.BAD_REQUEST, "APPLE_AUTH_FAILED", "Apple account email is not verified");
+    }
+    const normalizedEmail = normalizeEmailSafe(claims.email);
+    if (!normalizedEmail) {
+      return (0, import_core8.setApiResponse)(import_core8.HTTP.BAD_REQUEST, "APPLE_AUTH_FAILED", "Invalid email in Apple identity token");
+    }
+    const upserted = await users.upsertByProvider(normalizedEmail, "apple", claims.sub ?? "");
+    if (!upserted) {
+      loginEvents.recordSafe({
+        userId: null,
+        emailAttempted: normalizedEmail,
+        method: "oauth-apple",
+        outcome: "failed",
+        failureReason: "provider_upsert_failed",
+        ...meta
+      });
+      return (0, import_core8.setApiResponse)(import_core8.HTTP.SERVER_ERROR, "SERVER_ERROR", "Apple login failed");
+    }
+    const fullUser = await users.findById(upserted.id);
+    if (!fullUser) {
+      return (0, import_core8.setApiResponse)(import_core8.HTTP.SERVER_ERROR, "SERVER_ERROR", "Apple login failed");
+    }
+    const { accessToken, refreshToken, sid } = issueTokenPair(upserted.id, config, { loginMethod: "apple" });
+    await sessions.create(upserted.id, refreshToken, refreshTokenExpiry(refreshToken), sid, meta);
+    loginEvents.recordSafe({
+      userId: upserted.id,
+      emailAttempted: normalizedEmail,
+      method: "oauth-apple",
+      outcome: "success",
+      ...meta
+    });
+    return Response.json(
+      {
+        reason: "APPLE_AUTH_SUCCESS",
+        explanation: "Apple authentication successful.",
+        result: {
+          tokens: { access: accessToken, refresh: refreshToken },
+          user: toUserDTO(fullUser)
+        }
+      },
+      {
+        status: 200,
+        headers: cookieHeaders([
+          ...tokenPairCookies(accessToken, refreshToken, config),
+          // One-time value — clear the (SameSite=None) state cookie.
+          "oauth_state=; HttpOnly; SameSite=None; Secure; Path=/; Max-Age=0"
+        ])
+      }
+    );
+  };
   return {
     googleInit: async (_ctx) => {
       const google = config.google;
@@ -2451,6 +2571,113 @@ function oauthController(store, config) {
           ])
         }
       );
+    },
+    appleInit: async (_ctx) => {
+      const apple = config.apple;
+      if (!apple) {
+        return (0, import_core8.setApiResponse)(import_core8.HTTP.NOT_IMPLEMENTED, "NOT_CONFIGURED", "Apple OAuth not configured");
+      }
+      const state = (0, import_node_crypto7.randomBytes)(16).toString("hex");
+      const params = new URLSearchParams({
+        client_id: apple.clientId,
+        redirect_uri: apple.redirectUri,
+        response_type: "code",
+        // form_post is REQUIRED to receive name/email; Apple then POSTs the
+        // callback cross-site.
+        response_mode: "form_post",
+        scope: "name email",
+        state
+      });
+      const url = `${APPLE_AUTH_URL}?${params}`;
+      return Response.json(
+        {
+          reason: "APPLE_AUTH_URL",
+          explanation: "Redirect the user to the returned URL to begin Apple OAuth.",
+          result: { url }
+        },
+        {
+          status: 200,
+          headers: cookieHeaders([
+            `oauth_state=${state}; HttpOnly; SameSite=None; Secure; Path=/; Max-Age=600`
+          ])
+        }
+      );
+    },
+    appleCallback: async (ctx) => {
+      const apple = config.apple;
+      if (!apple) {
+        return (0, import_core8.setApiResponse)(import_core8.HTTP.NOT_IMPLEMENTED, "NOT_CONFIGURED", "Apple OAuth not configured");
+      }
+      const pre = ctx.meta["body"];
+      const form = pre && typeof pre === "object" ? new URLSearchParams(pre) : new URLSearchParams(await ctx.request.text());
+      const code = form.get("code");
+      if (!code) {
+        return (0, import_core8.setApiResponse)(import_core8.HTTP.BAD_REQUEST, "INVALID_PARAMETER", "Missing code");
+      }
+      const returnedState = form.get("state") ?? "";
+      const cookieHeader = ctx.request.headers.get("cookie") ?? "";
+      const expectedState = cookieHeader.match(/(?:^|;\s*)oauth_state=([^;]+)/)?.[1] ?? "";
+      if (!returnedState || !expectedState || !(0, import_core8.constantTimeEqual)(Buffer.from(returnedState), Buffer.from(expectedState))) {
+        return (0, import_core8.setApiResponse)(
+          import_core8.HTTP.BAD_REQUEST,
+          "APPLE_AUTH_FAILED",
+          "OAuth state mismatch \u2014 restart the sign-in flow"
+        );
+      }
+      const tokenRes = await fetch(APPLE_TOKEN_URL, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          code,
+          client_id: apple.clientId,
+          client_secret: mintAppleClientSecret(apple),
+          redirect_uri: apple.redirectUri,
+          grant_type: "authorization_code"
+        })
+      });
+      const tokenData = await tokenRes.json();
+      if (!tokenData.id_token) {
+        return (0, import_core8.setApiResponse)(import_core8.HTTP.BAD_REQUEST, "APPLE_AUTH_FAILED", "OAuth token exchange failed");
+      }
+      const claims = await verifyAppleIdToken(tokenData.id_token, { audiences: [apple.clientId] });
+      if (!claims) {
+        return (0, import_core8.setApiResponse)(import_core8.HTTP.BAD_REQUEST, "APPLE_AUTH_FAILED", "Invalid Apple identity token");
+      }
+      return completeAppleLogin(ctx, {
+        email: claims.email,
+        sub: claims.sub,
+        emailVerified: appleEmailVerified(claims)
+      });
+    },
+    appleNative: async (ctx) => {
+      const apple = config.apple;
+      if (!apple) {
+        return (0, import_core8.setApiResponse)(import_core8.HTTP.NOT_IMPLEMENTED, "NOT_CONFIGURED", "Apple OAuth not configured");
+      }
+      const body = ctx.meta["body"];
+      const identityToken = body?.identityToken;
+      if (!identityToken) {
+        return (0, import_core8.setApiResponse)(import_core8.HTTP.BAD_REQUEST, "INVALID_PARAMETER", "Missing identityToken");
+      }
+      const audiences = apple.nativeClientIds && apple.nativeClientIds.length ? apple.nativeClientIds : [apple.clientId];
+      const claims = await verifyAppleIdToken(identityToken, { audiences, nonce: body?.nonce });
+      if (!claims) {
+        const meta = requestMeta(ctx);
+        loginEvents.recordSafe({
+          userId: null,
+          emailAttempted: null,
+          method: "oauth-apple",
+          outcome: "failed",
+          failureReason: "invalid_identity_token",
+          ...meta
+        });
+        return (0, import_core8.setApiResponse)(import_core8.HTTP.UNAUTHORIZED, "APPLE_AUTH_FAILED", "Invalid Apple identity token");
+      }
+      return completeAppleLogin(ctx, {
+        email: claims.email,
+        sub: claims.sub,
+        emailVerified: appleEmailVerified(claims)
+      });
     }
   };
 }
@@ -2520,6 +2747,17 @@ function buildAuthRoutes(store, config, bus) {
       ["GET", "/auth/google/callback", oauth.googleCallback]
     );
   }
+  if (config.providers.includes("apple")) {
+    routes.push(
+      // Web redirect flow. The callback is a POST (response_mode=form_post);
+      // its urlencoded body is parsed inside the controller.
+      ["GET", "/auth/apple", oauth.appleInit],
+      ["POST", "/auth/apple/callback", oauth.appleCallback],
+      // Native (iOS) flow: the app posts the identityToken from the Apple
+      // sheet. ipLimit guards token brute-forcing; validate bounds the body.
+      ["POST", "/auth/apple/native", ipLimit("login"), (0, import_middlewares.validate)(appleNativeSchema), oauth.appleNative]
+    );
+  }
   return routes;
 }
 
@@ -2566,6 +2804,22 @@ function collectAuthConfigProblems(config) {
       });
     }
   }
+  if (config.apple) {
+    const a = config.apple;
+    if (!a.clientId || !a.teamId || !a.keyId || !a.privateKey || !a.redirectUri) {
+      problems.push({
+        module: MODULE,
+        severity: "error",
+        message: "apple OAuth is configured but clientId, teamId, keyId, privateKey, or redirectUri is missing"
+      });
+    } else if (!/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(a.privateKey)) {
+      problems.push({
+        module: MODULE,
+        severity: "error",
+        message: "apple.privateKey does not look like a PEM .p8 key (expected `-----BEGIN PRIVATE KEY-----`)"
+      });
+    }
+  }
   if (config.mfa && !config.mfaSecretKey) {
     problems.push({
       module: MODULE,