@fonderie/auth 7.1.1 → 7.3.0

package/brain/outcomes.md

@@ -9,6 +9,13 @@ downloading tarballs.
 
 ## Database tables (after all migrations)
 
+### `fonderie_consumed_tokens`
+
+```sql
+token_hash               TEXT PRIMARY KEY
+expires_at               TIMESTAMPTZ NOT NULL
+```
+
 ### `fonderie_email_verifications`
 
 ```sql
@@ -129,10 +136,13 @@ 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` | `ipLimit('login') → 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` |
-| GET | `/auth/google/callback` | `oauth.googleCallback` |
+| GET | `/auth/google/callback` | `ipLimit('login') → oauth.googleCallback` |
 | POST | `/auth/login` | `ipLimit('login') → validate(loginSchema) → acctLimit('login') → auth.login` |
 | GET | `/auth/login-history` | `requireAuth → user.loginHistory` |
 | POST | `/auth/logout` | `requireAuth → validate(refreshSchema) → auth.logout` |

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([
@@ -729,7 +736,8 @@ var UserModel = class {
       `INSERT INTO fonderie_users (email, email_verified_at, provider, provider_id)
 			VALUES ($1, now(), $2, $3)
 			ON CONFLICT (email) DO UPDATE
-			SET provider = $2, provider_id = $3
+			SET provider = $2, provider_id = $3,
+			    email_verified_at = COALESCE(fonderie_users.email_verified_at, now())
 			RETURNING id`,
       [email2, provider, providerId]
     );
@@ -2295,11 +2303,169 @@ 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");
+
+// src/models/consumed-token.model.ts
+var ConsumedTokenModel = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  // True if the token had not been consumed before (caller may proceed); false
+  // if this is a replay. `expiresAt` is the token's own exp — its TTL here.
+  async consumeOnce(tokenHash, expiresAt) {
+    const rows = await this.store.query(
+      `INSERT INTO fonderie_consumed_tokens (token_hash, expires_at)
+			 VALUES ($1, $2)
+			 ON CONFLICT (token_hash) DO NOTHING
+			 RETURNING token_hash`,
+      [tokenHash, expiresAt]
+    );
+    return rows.length > 0;
+  }
+  // Opportunistic, fire-and-forget cleanup of expired rows (index-backed).
+  // Recording history must never block or fail a login.
+  sweepExpiredSafe() {
+    void this.store.query(`DELETE FROM fonderie_consumed_tokens WHERE expires_at < now()`).catch(() => {
+    });
+  }
+};
+
+// src/controllers/oauth.controller.ts
+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 appleKeyInflight = null;
+var appleKeyLastAttempt = 0;
+var APPLE_KEYS_TTL_MS = 60 * 60 * 1e3;
+var APPLE_KEYS_MIN_REFETCH_MS = 60 * 1e3;
+var APPLE_KEYS_FETCH_TIMEOUT_MS = 5e3;
+function refreshAppleKeys() {
+  if (appleKeyInflight) return appleKeyInflight;
+  appleKeyLastAttempt = Date.now();
+  appleKeyInflight = (async () => {
+    try {
+      const res = await fetch(APPLE_KEYS_URL, { signal: AbortSignal.timeout(APPLE_KEYS_FETCH_TIMEOUT_MS) });
+      const data = await res.json();
+      if (Array.isArray(data.keys)) appleKeyCache = { keys: data.keys, fetchedAt: Date.now() };
+    } catch {
+    } finally {
+      appleKeyInflight = null;
+    }
+  })();
+  return appleKeyInflight;
+}
+async function getApplePublicKey(kid) {
+  const find = () => appleKeyCache?.keys.find((k) => k.kid === kid) ?? null;
+  const cacheFresh = () => !!appleKeyCache && Date.now() - appleKeyCache.fetchedAt < APPLE_KEYS_TTL_MS;
+  let jwk = find();
+  if ((!jwk || !cacheFresh()) && Date.now() - appleKeyLastAttempt >= APPLE_KEYS_MIN_REFETCH_MS) {
+    await refreshAppleKeys();
+    jwk = find();
+  }
+  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 consumedTokens = new ConsumedTokenModel(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 +2617,133 @@ 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");
+      }
+      const tokenHash = (0, import_node_crypto7.createHash)("sha256").update(identityToken).digest("hex");
+      const expMs = typeof claims.exp === "number" ? claims.exp * 1e3 : Date.now() + 5 * 60 * 1e3;
+      const firstUse = await consumedTokens.consumeOnce(tokenHash, new Date(expMs));
+      if (!firstUse) {
+        const meta = requestMeta(ctx);
+        loginEvents.recordSafe({
+          userId: null,
+          emailAttempted: claims.email ?? null,
+          method: "oauth-apple",
+          outcome: "failed",
+          failureReason: "token_replayed",
+          ...meta
+        });
+        return (0, import_core8.setApiResponse)(
+          import_core8.HTTP.UNAUTHORIZED,
+          "APPLE_AUTH_FAILED",
+          "This Apple identity token has already been used"
+        );
+      }
+      consumedTokens.sweepExpiredSafe();
+      return completeAppleLogin(ctx, {
+        email: claims.email,
+        sub: claims.sub,
+        emailVerified: appleEmailVerified(claims)
+      });
     }
   };
 }
@@ -2517,7 +2810,21 @@ function buildAuthRoutes(store, config, bus) {
   if (config.providers.includes("google")) {
     routes.push(
       ["GET", "/auth/google", oauth.googleInit],
-      ["GET", "/auth/google/callback", oauth.googleCallback]
+      // ipLimit: an unauthenticated caller can otherwise force one outbound
+      // token-exchange to Google per request (the state check doesn't gate it).
+      ["GET", "/auth/google/callback", ipLimit("login"), 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. ipLimit for the
+      // same reason as Google's callback (bounds outbound token exchanges).
+      ["GET", "/auth/apple", oauth.appleInit],
+      ["POST", "/auth/apple/callback", ipLimit("login"), 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 +2873,29 @@ 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 (a.nativeClientIds?.some((id) => !id || id.trim() === "" || id.includes("*"))) {
+      problems.push({
+        module: MODULE,
+        severity: "error",
+        message: "apple.nativeClientIds must be exact bundle ids \u2014 empty or wildcard entries would accept identity tokens minted for other apps"
+      });
+    }
+  }
   if (config.mfa && !config.mfaSecretKey) {
     problems.push({
       module: MODULE,