fix(login): Improve Passkey Authentication Error Handling & Testing (#10971)

# Which Problems Are Solved

This PR enhances the passkey authentication flow with comprehensive
error handling, full internationalization support, and extensive test
coverage.

# How the Problems Are Solved

I18n:
- Replaced all hard-coded error messages with i18n translation keys
- Consistent error messaging throughout the passkey flow
- Added specific error handling for passkey cancellation
(NotAllowedError)
- Implemented fallback errors for undefined/missing responses
- Better error messages for:
  - Session retrieval failures
  - Challenge request failures
  - User verification errors
  - Redirect determination issues

Tests:
- Added `login-passkey.test.tsx` with 100+ test cases covering:
  - Successful verification flows
  - Error scenarios and edge cases
  - Props handling
  - Component lifecycle
- Added passkeys.test.ts with server-side function tests:
  - Session cookie retrieval
  - User validation
  - Custom lifetime handling
  - Critical fallback error paths
  
Try-catch blocks around critical user retrieval operations
Defensive checks for undefined responses from completeFlowOrGetUrl
Support for custom lifetime parameters
Cleaner error propagation
This commit is contained in:
Max Peintner
2025-10-27 14:38:04 +00:00
committed by GitHub
parent c4221a9c0f
commit d5d68aed4b
14 changed files with 1112 additions and 83 deletions
+413
View File
@@ -0,0 +1,413 @@
import { describe, expect, test, vi, beforeEach } from "vitest";
import { sendPasskey } from "./passkeys";
// Mock all the dependencies
vi.mock("next/headers", () => ({
headers: vi.fn(),
}));
vi.mock("@zitadel/client", () => ({
create: vi.fn(),
Duration: vi.fn(),
Timestamp: vi.fn(),
timestampDate: vi.fn(),
}));
vi.mock("../service-url", () => ({
getServiceUrlFromHeaders: vi.fn(),
}));
vi.mock("../zitadel", () => ({
getLoginSettings: vi.fn(),
getUserByID: vi.fn(),
}));
vi.mock("./cookie", () => ({
setSessionAndUpdateCookie: vi.fn(),
}));
vi.mock("../cookies", () => ({
getSessionCookieById: vi.fn(),
getSessionCookieByLoginName: vi.fn(),
getMostRecentSessionCookie: vi.fn(),
}));
vi.mock("../verify-helper", () => ({
checkEmailVerification: vi.fn(),
}));
vi.mock("../client", () => ({
completeFlowOrGetUrl: vi.fn(),
}));
// Mock translations - returns the key itself for testing
vi.mock("next-intl/server", () => ({
getTranslations: vi.fn(() => (key: string) => key),
}));
describe("sendPasskey", () => {
let mockHeaders: any;
let mockGetServiceUrlFromHeaders: any;
let mockGetLoginSettings: any;
let mockGetUserByID: any;
let mockSetSessionAndUpdateCookie: any;
let mockGetSessionCookieById: any;
let mockGetSessionCookieByLoginName: any;
let mockGetMostRecentSessionCookie: any;
let mockCheckEmailVerification: any;
let mockCompleteFlowOrGetUrl: any;
beforeEach(async () => {
vi.clearAllMocks();
// Import mocked modules
const { headers } = await import("next/headers");
const { getServiceUrlFromHeaders } = await import("../service-url");
const { getLoginSettings, getUserByID } = await import("../zitadel");
const { setSessionAndUpdateCookie } = await import("./cookie");
const { getSessionCookieById, getSessionCookieByLoginName, getMostRecentSessionCookie } = await import("../cookies");
const { checkEmailVerification } = await import("../verify-helper");
const { completeFlowOrGetUrl } = await import("../client");
// Setup mocks
mockHeaders = vi.mocked(headers);
mockGetServiceUrlFromHeaders = vi.mocked(getServiceUrlFromHeaders);
mockGetLoginSettings = vi.mocked(getLoginSettings);
mockGetUserByID = vi.mocked(getUserByID);
mockSetSessionAndUpdateCookie = vi.mocked(setSessionAndUpdateCookie);
mockGetSessionCookieById = vi.mocked(getSessionCookieById);
mockGetSessionCookieByLoginName = vi.mocked(getSessionCookieByLoginName);
mockGetMostRecentSessionCookie = vi.mocked(getMostRecentSessionCookie);
mockCheckEmailVerification = vi.mocked(checkEmailVerification);
mockCompleteFlowOrGetUrl = vi.mocked(completeFlowOrGetUrl);
// Default mock implementations
mockHeaders.mockResolvedValue(new Headers());
mockGetServiceUrlFromHeaders.mockReturnValue({
serviceUrl: "https://example.com",
});
mockGetLoginSettings.mockResolvedValue({
multiFactorCheckLifetime: {
seconds: BigInt(300),
nanos: 0,
},
});
});
describe("Session Cookie Retrieval", () => {
test("should return error when session cookie not found by sessionId", async () => {
mockGetSessionCookieById.mockResolvedValue(null);
const result = await sendPasskey({
sessionId: "test-session-id",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
error: "verify.errors.couldNotFindSession",
});
expect(mockGetSessionCookieById).toHaveBeenCalledWith({
sessionId: "test-session-id",
});
});
test("should return error when session cookie is not found by loginName", async () => {
mockGetSessionCookieByLoginName.mockResolvedValue(null);
const result = await sendPasskey({
loginName: "[email protected]",
organization: "org-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
error: "verify.errors.couldNotFindSession",
});
expect(mockGetSessionCookieByLoginName).toHaveBeenCalledWith({
loginName: "[email protected]",
organization: "org-123",
});
});
test("should return error when no session cookie found (most recent fallback)", async () => {
mockGetMostRecentSessionCookie.mockResolvedValue(null);
const result = await sendPasskey({
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
error: "verify.errors.couldNotFindSession",
});
expect(mockGetMostRecentSessionCookie).toHaveBeenCalled();
});
});
describe("Session Update Failures", () => {
beforeEach(() => {
mockGetSessionCookieById.mockResolvedValue({
id: "session-123",
token: "session-token",
loginName: "[email protected]",
});
});
test("should return error when setSessionAndUpdateCookie fails", async () => {
mockSetSessionAndUpdateCookie.mockResolvedValue({
error: "Failed to update session",
});
const result = await sendPasskey({
sessionId: "session-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
error: "verify.errors.couldNotUpdateSession",
});
});
test("should return error when setSessionAndUpdateCookie returns undefined", async () => {
mockSetSessionAndUpdateCookie.mockResolvedValue(undefined as any);
const result = await sendPasskey({
sessionId: "session-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
error: "verify.errors.couldNotUpdateSession",
});
});
});
describe("User Validation", () => {
beforeEach(() => {
mockGetSessionCookieById.mockResolvedValue({
id: "session-123",
token: "session-token",
loginName: "[email protected]",
});
mockSetSessionAndUpdateCookie.mockResolvedValue({
sessionId: "session-123",
sessionToken: "new-token",
factors: {
user: {
id: "user-123",
},
},
});
});
test("should return error when getUserByID fails", async () => {
mockGetUserByID.mockRejectedValue(new Error("User not found"));
const result = await sendPasskey({
sessionId: "session-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
error: "verify.errors.couldNotGetUser",
});
});
});
describe("Successful Passkey Verification", () => {
beforeEach(() => {
mockGetSessionCookieById.mockResolvedValue({
id: "session-123",
token: "session-token",
loginName: "[email protected]",
});
mockSetSessionAndUpdateCookie.mockResolvedValue({
id: "session-123",
factors: {
user: {
id: "user-123",
loginName: "[email protected]",
},
},
});
mockGetUserByID.mockResolvedValue({
user: {
id: "user-123",
type: {
case: "human",
value: {
email: {
isVerified: true,
},
},
},
},
});
mockCheckEmailVerification.mockResolvedValue(true);
});
test("should redirect on successful verification without requestId", async () => {
mockCompleteFlowOrGetUrl.mockResolvedValue({ redirect: "/dashboard" });
const result = await sendPasskey({
sessionId: "session-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
redirect: "/dashboard",
});
});
test("should redirect on successful verification with requestId", async () => {
mockCompleteFlowOrGetUrl.mockResolvedValue({ redirect: "/auth/callback" });
const result = await sendPasskey({
sessionId: "session-123",
requestId: "request-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
redirect: "/auth/callback",
});
});
test("should redirect for email verification when required", async () => {
mockCheckEmailVerification.mockReturnValue({ redirect: "/verify" });
const result = await sendPasskey({
sessionId: "session-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toHaveProperty("redirect");
if ("redirect" in result) {
expect(result.redirect).toContain("/verify");
}
});
});
describe("Fallback Error Handling - Critical Fix", () => {
beforeEach(() => {
mockGetSessionCookieById.mockResolvedValue({
id: "session-123",
token: "session-token",
loginName: "[email protected]",
});
mockSetSessionAndUpdateCookie.mockResolvedValue({
id: "session-123",
factors: {
user: {
id: "user-123",
loginName: "[email protected]",
},
},
});
mockGetUserByID.mockResolvedValue({
user: {
id: "user-123",
type: {
case: "human",
value: {
email: {
isVerified: true,
},
},
},
},
});
mockCheckEmailVerification.mockResolvedValue(true);
});
test("should return fallback error when completeFlowOrGetUrl returns undefined", async () => {
mockCompleteFlowOrGetUrl.mockResolvedValue(undefined);
const result = await sendPasskey({
sessionId: "session-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
error: "verify.errors.couldNotDetermineRedirect",
});
});
test("should return fallback error when completeFlowOrGetUrl returns empty string", async () => {
mockCompleteFlowOrGetUrl.mockResolvedValue("");
const result = await sendPasskey({
sessionId: "session-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(result).toEqual({
error: "verify.errors.couldNotDetermineRedirect",
});
});
});
describe("Custom Lifetime Handling", () => {
beforeEach(() => {
mockGetSessionCookieById.mockResolvedValue({
id: "session-123",
token: "session-token",
loginName: "[email protected]",
});
mockSetSessionAndUpdateCookie.mockResolvedValue({
id: "session-123",
factors: {
user: {
id: "user-123",
loginName: "[email protected]",
},
},
});
mockGetUserByID.mockResolvedValue({
user: {
id: "user-123",
type: {
case: "human",
value: {
email: {
isVerified: true,
},
},
},
},
});
mockCheckEmailVerification.mockResolvedValue(true);
mockCompleteFlowOrGetUrl.mockResolvedValue({ redirect: "/dashboard" });
});
test("should use custom lifetime when provided", async () => {
await sendPasskey({
sessionId: "session-123",
lifetime: { seconds: BigInt(600), nanos: 0 } as any,
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(mockSetSessionAndUpdateCookie).toHaveBeenCalledWith(
expect.objectContaining({
lifetime: expect.objectContaining({
seconds: BigInt(600),
}),
}),
);
});
test("should use default lifetime from login settings when not provided", async () => {
await sendPasskey({
sessionId: "session-123",
checks: { webAuthN: { credentialAssertionData: {} } } as any,
});
expect(mockSetSessionAndUpdateCookie).toHaveBeenCalledWith(
expect.objectContaining({
lifetime: expect.objectContaining({
seconds: BigInt(300),
}),
}),
);
});
});
});
+41 -14
View File
@@ -18,6 +18,7 @@ import {
} from "@zitadel/proto/zitadel/user/v2/user_service_pb";
import { headers } from "next/headers";
import { userAgent } from "next/server";
import { getTranslations } from "next-intl/server";
import { getMostRecentSessionCookie, getSessionCookieById, getSessionCookieByLoginName } from "../cookies";
import { getServiceUrlFromHeaders } from "../service-url";
import { checkEmailVerification, checkUserVerification } from "../verify-helper";
@@ -262,6 +263,9 @@ type SendPasskeyCommand = {
export async function sendPasskey(command: SendPasskeyCommand) {
let { loginName, sessionId, organization, checks, requestId } = command;
const t = await getTranslations("passkey");
const recentSession = sessionId
? await getSessionCookieById({ sessionId })
: loginName
@@ -270,7 +274,7 @@ export async function sendPasskey(command: SendPasskeyCommand) {
if (!recentSession) {
return {
error: "Could not find session",
error: t("verify.errors.couldNotFindSession"),
};
}
@@ -282,11 +286,15 @@ export async function sendPasskey(command: SendPasskeyCommand) {
organization,
});
let lifetime = checks?.webAuthN
? loginSettings?.multiFactorCheckLifetime // TODO different lifetime for webauthn u2f/passkey
: checks?.otpEmail || checks?.otpSms
? loginSettings?.secondFactorCheckLifetime
: undefined;
let lifetime = command.lifetime; // Use provided lifetime first
if (!lifetime) {
lifetime = checks?.webAuthN
? loginSettings?.multiFactorCheckLifetime // TODO different lifetime for webauthn u2f/passkey
: checks?.otpEmail || checks?.otpSms
? loginSettings?.secondFactorCheckLifetime
: undefined;
}
if (!lifetime || !lifetime.seconds) {
console.warn("No passkey lifetime provided, defaulting to 24 hours");
@@ -305,16 +313,22 @@ export async function sendPasskey(command: SendPasskeyCommand) {
});
if (!session || !session?.factors?.user?.id) {
return { error: "Could not update session" };
return { error: t("verify.errors.couldNotUpdateSession") };
}
const userResponse = await getUserByID({
serviceUrl,
userId: session?.factors?.user?.id,
});
let userResponse;
try {
userResponse = await getUserByID({
serviceUrl,
userId: session?.factors?.user?.id,
});
} catch (error) {
console.error("Error fetching user by ID:", error);
return { error: t("verify.errors.couldNotGetUser") };
}
if (!userResponse.user) {
return { error: "User not found in the system" };
return { error: t("verify.errors.userNotFound") };
}
const humanUser = userResponse.user.type.case === "human" ? userResponse.user.type.value : undefined;
@@ -325,8 +339,9 @@ export async function sendPasskey(command: SendPasskeyCommand) {
return emailVerificationCheck;
}
let redirectResult;
if (requestId && session.id) {
return completeFlowOrGetUrl(
redirectResult = await completeFlowOrGetUrl(
{
sessionId: session.id,
requestId: requestId,
@@ -335,7 +350,7 @@ export async function sendPasskey(command: SendPasskeyCommand) {
loginSettings?.defaultRedirectUri,
);
} else if (session?.factors?.user?.loginName) {
return completeFlowOrGetUrl(
redirectResult = await completeFlowOrGetUrl(
{
loginName: session.factors.user.loginName,
organization: organization,
@@ -343,4 +358,16 @@ export async function sendPasskey(command: SendPasskeyCommand) {
loginSettings?.defaultRedirectUri,
);
}
// Check if we got a valid redirect result
if (redirectResult && typeof redirectResult === "object" && "redirect" in redirectResult && redirectResult.redirect) {
return redirectResult;
}
if (redirectResult && typeof redirectResult === "object" && "error" in redirectResult) {
return redirectResult;
}
// Fallback error if we couldn't determine where to redirect
return { error: t("verify.errors.couldNotDetermineRedirect") };
}
+6
View File
@@ -13,6 +13,7 @@ import { RequestChallenges } from "@zitadel/proto/zitadel/session/v2/challenge_p
import { Session } from "@zitadel/proto/zitadel/session/v2/session_pb";
import { Checks } from "@zitadel/proto/zitadel/session/v2/session_service_pb";
import { headers } from "next/headers";
import { getTranslations } from "next-intl/server";
import { completeFlowOrGetUrl } from "../client";
import {
getMostRecentSessionCookie,
@@ -74,6 +75,8 @@ export async function continueWithSession({ requestId, ...session }: ContinueWit
const _headers = await headers();
const { serviceUrl } = getServiceUrlFromHeaders(_headers);
const t = await getTranslations("error");
const loginSettings = await getLoginSettings({
serviceUrl,
organization: session.factors?.user?.organizationId,
@@ -97,6 +100,9 @@ export async function continueWithSession({ requestId, ...session }: ContinueWit
loginSettings?.defaultRedirectUri,
);
}
// Fallback error if we couldn't determine where to redirect
return { error: t("couldNotContinueSession") };
}
export type UpdateSessionCommand = {