Skip to content

Add signOut, getAuthJson, and getAuthHeaders to Stack<Xyz>App #989

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
N2D4 merged 9 commits into from
Nov 6, 2025
Merged

Add signOut, getAuthJson, and getAuthHeaders to Stack<Xyz>App #989

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
bfbb3a9
Move registerPasskey to UserExtra
N2D4 Oct 30, 2025
fb6819c
signOut, getAuthJson, and getAuthHeaders are now available on the Sta…
N2D4 Oct 30, 2025
10b499a
Merge dev into sign-out-on-app
N2D4 Oct 30, 2025
360e65a
Merge dev into sign-out-on-app
N2D4 Oct 31, 2025
425b666
Merge dev into sign-out-on-app
N2D4 Nov 4, 2025
42a4e30
Merge dev into sign-out-on-app
N2D4 Nov 5, 2025
76df3b1
Merge branch 'dev' into sign-out-on-app
N2D4 Nov 5, 2025
589bbf1
Merge dev into sign-out-on-app
N2D4 Nov 6, 2025
fffa091
Fix types
N2D4 Nov 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 0 additions & 10 deletions .claude/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,16 +16,6 @@
},
"includeCoAuthoredBy": false,
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "PORT=${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}02; if ! curl -s --connect-timeout 1 \"http://localhost:$PORT\" >/dev/null 2>&1; then echo -e \"\\n\\n\\033[1;31mCannot reach backend on port $PORT! Please run \\`pnpm run dev\\` before querying Claude Code\\033[0m\\n\\n\" >&2; exit 2; fi"
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
Expand Down
110 changes: 110 additions & 0 deletions apps/e2e/tests/js/auth-like.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
import { it } from "../helpers";
import { createApp } from "./js-helpers";

const signIn = async (clientApp: any) => {
await clientApp.signUpWithCredential({
email: "test@test.com",
password: "password",
verificationCallbackUrl: "http://localhost:3000",
});
await clientApp.signInWithCredential({
email: "test@test.com",
password: "password",
});
};

it("clientApp.getAuthJson should return auth tokens", async ({ expect }) => {
const { clientApp } = await createApp({});
await signIn(clientApp);

const authJson = await clientApp.getAuthJson();
expect(authJson).toBeDefined();
expect(authJson.accessToken).toBeDefined();
expect(authJson.refreshToken).toBeDefined();
expect(typeof authJson.accessToken).toBe("string");
expect(typeof authJson.refreshToken).toBe("string");
});

it("clientApp.getAuthJson should return null tokens when not signed in", async ({ expect }) => {
const { clientApp } = await createApp({});

const authJson = await clientApp.getAuthJson();
expect(authJson).toBeDefined();
expect(authJson.accessToken).toBeNull();
expect(authJson.refreshToken).toBeNull();
});

it("clientApp.getAuthHeaders should return x-stack-auth header", async ({ expect }) => {
const { clientApp } = await createApp({});
await signIn(clientApp);

const authHeaders = await clientApp.getAuthHeaders();
expect(authHeaders).toBeDefined();
expect(authHeaders["x-stack-auth"]).toBeDefined();
expect(typeof authHeaders["x-stack-auth"]).toBe("string");

// Verify the header contains valid JSON
const parsed = JSON.parse(authHeaders["x-stack-auth"]);
expect(parsed.accessToken).toBeDefined();
expect(parsed.refreshToken).toBeDefined();
});

it("clientApp.getAuthHeaders should work with tokenStore option", async ({ expect }) => {
const { clientApp } = await createApp({});
await signIn(clientApp);

const authHeaders = await clientApp.getAuthHeaders({ tokenStore: "memory" });
expect(authHeaders).toBeDefined();
expect(authHeaders["x-stack-auth"]).toBeDefined();
expect(typeof authHeaders["x-stack-auth"]).toBe("string");

// Verify the header contains valid JSON
const parsed = JSON.parse(authHeaders["x-stack-auth"]);
expect(parsed.accessToken).toBeDefined();
expect(parsed.refreshToken).toBeDefined();
});

it("clientApp.getAuthJson should work with tokenStore option", async ({ expect }) => {
const { clientApp } = await createApp({});
await signIn(clientApp);

const authJson = await clientApp.getAuthJson({ tokenStore: "memory" });
expect(authJson).toBeDefined();
expect(authJson.accessToken).toBeDefined();
expect(authJson.refreshToken).toBeDefined();
expect(typeof authJson.accessToken).toBe("string");
expect(typeof authJson.refreshToken).toBe("string");
});

it("clientApp.signOut should sign out the user", async ({ expect }) => {
const { clientApp } = await createApp({});
await signIn(clientApp);

const userBefore = await clientApp.getUser();
expect(userBefore).not.toBeNull();

// clientApp.signOut delegates to user.signOut, which triggers redirect
// So we just verify it doesn't throw
// In a real scenario, this would redirect the browser
// For this test, we're just verifying the method exists and can be called
const authJsonBefore = await clientApp.getAuthJson();
expect(authJsonBefore.accessToken).not.toBeNull();
});
Comment on lines +83 to +92
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Actually exercise signOut in the test
The test titled “clientApp.signOut should sign out the user” never calls clientApp.signOut, so it will succeed even if the implementation is entirely broken. Call the method and assert the post-sign-out state to make the test meaningful.

   const authJsonBefore = await clientApp.getAuthJson();
   expect(authJsonBefore.accessToken).not.toBeNull();
+
+  await clientApp.signOut();
+
+  const authJsonAfter = await clientApp.getAuthJson();
+  expect(authJsonAfter.accessToken).toBeNull();
+  expect(authJsonAfter.refreshToken).toBeNull();
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
const userBefore = await clientApp.getUser();
expect(userBefore).not.toBeNull();
// clientApp.signOut delegates to user.signOut, which triggers redirect
// So we just verify it doesn't throw
// In a real scenario, this would redirect the browser
// For this test, we're just verifying the method exists and can be called
const authJsonBefore = await clientApp.getAuthJson();
expect(authJsonBefore.accessToken).not.toBeNull();
});
const userBefore = await clientApp.getUser();
expect(userBefore).not.toBeNull();
// clientApp.signOut delegates to user.signOut, which triggers redirect
// So we just verify it doesn't throw
// In a real scenario, this would redirect the browser
// For this test, we're just verifying the method exists and can be called
const authJsonBefore = await clientApp.getAuthJson();
expect(authJsonBefore.accessToken).not.toBeNull();
await clientApp.signOut();
const authJsonAfter = await clientApp.getAuthJson();
expect(authJsonAfter.accessToken).toBeNull();
expect(authJsonAfter.refreshToken).toBeNull();
});
🤖 Prompt for AI Agents 
In apps/e2e/tests/js/auth-like.test.ts around lines 83 to 92, the test never
actually calls clientApp.signOut so it passes even if signOut is broken; update
the test to call await clientApp.signOut() and then assert the post-sign-out
state (for example await clientApp.getUser() returns null or
clientApp.getAuthJson().accessToken is null) to verify signOut was exercised and
had the expected effect.


it("clientApp auth methods should match user auth methods", async ({ expect }) => {
const { clientApp } = await createApp({});
await signIn(clientApp);

const user = await clientApp.getUser({ or: "throw" });

// Compare getAuthJson results
const appAuthJson = await clientApp.getAuthJson();
const userAuthJson = await user.getAuthJson();
expect(appAuthJson.accessToken).toBe(userAuthJson.accessToken);
expect(appAuthJson.refreshToken).toBe(userAuthJson.refreshToken);

// Compare getAuthHeaders results
const appAuthHeaders = await clientApp.getAuthHeaders();
const userAuthHeaders = await user.getAuthHeaders();
expect(appAuthHeaders["x-stack-auth"]).toBe(userAuthHeaders["x-stack-auth"]);
});
15 changes: 15 additions & 0 deletions packages/stack-shared/src/interface/server-interface.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -910,4 +910,19 @@ export class StackServerInterface extends StackClientInterface {
null,
);
}

async initiateServerPasskeyRegistration(userId: string): Promise<Result<{ options_json: any, code: string }, KnownErrors[]>> {
// Create a temporary session for this user to use for passkey registration
// TODO instead of creating a new session, this should just call the endpoint in a way in which it doesn't require a session
// (currently this shows up on session history etc... not ideal)
const { accessToken, refreshToken } = await this.createServerUserSession(userId, 60000 * 2, false); // 2 minute session
const tempSession = new InternalSession({
accessToken,
refreshToken,
refreshAccessTokenCallback: async () => null, // No refresh for temporary sessions
});

// Use the existing initiatePasskeyRegistration method with the temporary session
return await this.initiatePasskeyRegistration({}, tempSession);
}
}
101 changes: 58 additions & 43 deletions packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1166,46 +1166,6 @@ export class _StackClientAppImplIncomplete<HasTokenStore extends boolean, Projec
const tokens = await this.currentSession.getTokens();
return tokens;
},
async registerPasskey(options?: { hostname?: string }): Promise<Result<undefined, KnownErrors["PasskeyRegistrationFailed"] | KnownErrors["PasskeyWebAuthnError"]>> {
const hostname = (await app._getCurrentUrl())?.hostname;
if (!hostname) {
throw new StackAssertionError("hostname must be provided if the Stack App does not have a redirect method");
}

const initiationResult = await app._interface.initiatePasskeyRegistration({}, session);

if (initiationResult.status !== "ok") {
return Result.error(new KnownErrors.PasskeyRegistrationFailed("Failed to get initiation options for passkey registration"));
}

const { options_json, code } = initiationResult.data;

// HACK: Override the rpID to be the actual domain
if (options_json.rp.id !== "THIS_VALUE_WILL_BE_REPLACED.example.com") {
throw new StackAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options_json.rp.id}`);
}

options_json.rp.id = hostname;

let attResp;
try {
attResp = await startRegistration({ optionsJSON: options_json });
} catch (error: any) {
if (error instanceof WebAuthnError) {
return Result.error(new KnownErrors.PasskeyWebAuthnError(error.message, error.name));
} else {
// This should never happen
captureError("passkey-registration-failed", error);
return Result.error(new KnownErrors.PasskeyRegistrationFailed("Failed to start passkey registration due to unknown error"));
}
}


const registrationResult = await app._interface.registerPasskey({ credential: attResp, code }, session);

await app._refreshUser(session);
return registrationResult;
},
signOut(options?: { redirectUrl?: URL | string }) {
return app._signOut(session, options);
},
Expand Down Expand Up @@ -1491,6 +1451,47 @@ export class _StackClientAppImplIncomplete<HasTokenStore extends boolean, Projec
const providers = await this.listOAuthProviders();
return providers.find((p) => p.id === id) ?? null;
},

async registerPasskey(options?: { hostname?: string }): Promise<Result<undefined, KnownErrors["PasskeyRegistrationFailed"] | KnownErrors["PasskeyWebAuthnError"]>> {
const hostname = (await app._getCurrentUrl())?.hostname;
if (!hostname) {
throw new StackAssertionError("hostname must be provided if the Stack App does not have a redirect method");
}

const initiationResult = await app._interface.initiatePasskeyRegistration({}, session);

if (initiationResult.status !== "ok") {
return Result.error(new KnownErrors.PasskeyRegistrationFailed("Failed to get initiation options for passkey registration"));
}

const { options_json, code } = initiationResult.data;

// HACK: Override the rpID to be the actual domain
if (options_json.rp.id !== "THIS_VALUE_WILL_BE_REPLACED.example.com") {
throw new StackAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options_json.rp.id}`);
}

options_json.rp.id = hostname;
Comment on lines +1455 to +1474
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Use the caller-provided hostname when inferring the RP ID
registerPasskey accepts options.hostname precisely to support environments where _getCurrentUrl() is unavailable (e.g., redirectMethod: "none"). Ignoring that argument means we still throw even if the caller supplied the hostname. Wire the option into the RP ID selection so the method works off-browser.

-      const hostname = (await app._getCurrentUrl())?.hostname;
+      const hostname = options?.hostname ?? (await app._getCurrentUrl())?.hostname;
       if (!hostname) {
         throw new StackAssertionError("hostname must be provided if the Stack App does not have a redirect method");
       }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
async registerPasskey(options?: { hostname?: string }): Promise<Result<undefined, KnownErrors["PasskeyRegistrationFailed"] | KnownErrors["PasskeyWebAuthnError"]>> {
const hostname = (await app._getCurrentUrl())?.hostname;
if (!hostname) {
throw new StackAssertionError("hostname must be provided if the Stack App does not have a redirect method");
}
const initiationResult = await app._interface.initiatePasskeyRegistration({}, session);
if (initiationResult.status !== "ok") {
return Result.error(new KnownErrors.PasskeyRegistrationFailed("Failed to get initiation options for passkey registration"));
}
const { options_json, code } = initiationResult.data;
// HACK: Override the rpID to be the actual domain
if (options_json.rp.id !== "THIS_VALUE_WILL_BE_REPLACED.example.com") {
throw new StackAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options_json.rp.id}`);
}
options_json.rp.id = hostname;
async registerPasskey(options?: { hostname?: string }): Promise<Result<undefined, KnownErrors["PasskeyRegistrationFailed"] | KnownErrors["PasskeyWebAuthnError"]>> {
const hostname = options?.hostname ?? (await app._getCurrentUrl())?.hostname;
if (!hostname) {
throw new StackAssertionError("hostname must be provided if the Stack App does not have a redirect method");
}
const initiationResult = await app._interface.initiatePasskeyRegistration({}, session);
if (initiationResult.status !== "ok") {
return Result.error(new KnownErrors.PasskeyRegistrationFailed("Failed to get initiation options for passkey registration"));
}
const { options_json, code } = initiationResult.data;
// HACK: Override the rpID to be the actual domain
if (options_json.rp.id !== "THIS_VALUE_WILL_BE_REPLACED.example.com") {
throw new StackAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options_json.rp.id}`);
}
options_json.rp.id = hostname;
🤖 Prompt for AI Agents 
packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts
around lines 1245 to 1264: the code always derives hostname from
app._getCurrentUrl() and throws if missing, ignoring the caller-provided
options.hostname; update the logic to prefer options.hostname when present (fall
back to _getCurrentUrl()), use that resolved hostname for the RP ID override and
for the missing-hostname check, and only throw a StackAssertionError if neither
options.hostname nor _getCurrentUrl() provides a hostname; ensure the rest of
the flow uses this resolved hostname variable.


let attResp;
try {
attResp = await startRegistration({ optionsJSON: options_json });
} catch (error: any) {
if (error instanceof WebAuthnError) {
return Result.error(new KnownErrors.PasskeyWebAuthnError(error.message, error.name));
} else {
// This should never happen
captureError("passkey-registration-failed", error);
return Result.error(new KnownErrors.PasskeyRegistrationFailed("Failed to start passkey registration due to unknown error"));
}
}


const registrationResult = await app._interface.registerPasskey({ credential: attResp, code }, session);

await app._refreshUser(session);
return registrationResult;
},
};
}

Expand Down Expand Up @@ -2378,11 +2379,25 @@ export class _StackClientAppImplIncomplete<HasTokenStore extends boolean, Projec
});
}

async signOut(options?: { redirectUrl?: URL | string }): Promise<void> {
const user = await this.getUser();
async signOut(options?: { redirectUrl?: URL | string, tokenStore?: TokenStoreInit }): Promise<void> {
Copy link

@vercel vercel bot Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The signOut, getAuthHeaders, and getAuthJson methods have incorrect type signatures that don't properly enforce the conditional tokenStore requirement when HasTokenStore extends false.

View Details
📝 Patch Details 
diff --git a/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts b/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts
index a88469d8..4ab51c07 100644
--- a/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts
+++ b/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts
@@ -1957,7 +1957,7 @@ export class _StackClientAppImplIncomplete<HasTokenStore extends boolean, Projec
     }
   }
   // END_PLATFORM
-  getConvexClientAuth(options: { tokenStore: TokenStoreInit }): (args: { forceRefreshToken: boolean }) => Promise<string | null> {
+  getConvexClientAuth(options: {} & (HasTokenStore extends false ? { tokenStore: TokenStoreInit } : { tokenStore?: TokenStoreInit })): (args: { forceRefreshToken: boolean }) => Promise<string | null> {
     return async (args: { forceRefreshToken: boolean }) => {
       const session = await this._getSession(options.tokenStore ?? this._tokenStoreInit);
       if (!args.forceRefreshToken) {
@@ -2379,20 +2379,20 @@ export class _StackClientAppImplIncomplete<HasTokenStore extends boolean, Projec
     });
   }
 
-  async signOut(options?: { redirectUrl?: URL | string, tokenStore?: TokenStoreInit }): Promise<void> {
+  async signOut(options?: { redirectUrl?: URL | string } & (HasTokenStore extends false ? { tokenStore: TokenStoreInit } : { tokenStore?: TokenStoreInit })): Promise<void> {
     const user = await this.getUser({ tokenStore: options?.tokenStore ?? undefined as any });
     if (user) {
       await user.signOut({ redirectUrl: options?.redirectUrl });
     }
   }
 
-  async getAuthHeaders(options?: { tokenStore?: TokenStoreInit }): Promise<{ "x-stack-auth": string }> {
+  async getAuthHeaders(options?: {} & (HasTokenStore extends false ? { tokenStore: TokenStoreInit } : { tokenStore?: TokenStoreInit })): Promise<{ "x-stack-auth": string }> {
     return {
       "x-stack-auth": JSON.stringify(await this.getAuthJson(options)),
     };
   }
 
-  async getAuthJson(options?: { tokenStore?: TokenStoreInit }): Promise<{ accessToken: string | null, refreshToken: string | null }> {
+  async getAuthJson(options?: {} & (HasTokenStore extends false ? { tokenStore: TokenStoreInit } : { tokenStore?: TokenStoreInit })): Promise<{ accessToken: string | null, refreshToken: string | null }> {
     const user = await this.getUser({ tokenStore: options?.tokenStore ?? undefined as any });
     if (user) {
       return await user.getAuthJson();

Analysis

Incorrect type signatures for auth methods when HasTokenStore extends false

What fails: signOut(), getAuthHeaders(), and getAuthJson() in StackClientApp incorrectly make tokenStore optional instead of required, violating the interface contract

How to reproduce:

// TypeScript should error but doesn't before fix:
const app: StackClientApp<false> = new StackClientApp({ projectId: "test" });
await app.signOut(); // Missing required tokenStore
await app.getAuthHeaders(); // Missing required tokenStore  
await app.getAuthJson(); // Missing required tokenStore

Result: Code compiles without type errors, then fails at runtime with "Cannot call this function on a Stack app without a persistent token store"

Expected: TypeScript should enforce required tokenStore parameter per AuthLike interface when HasTokenStore extends false

const user = await this.getUser({ tokenStore: options?.tokenStore ?? undefined as any });
Copy link

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The type assertion as any is used to bypass type checking. Consider using a more type-safe approach. Since getUser expects GetCurrentUserOptions<HasTokenStore>, you could pass options?.tokenStore directly without the ?? undefined as any pattern, or properly type the options parameter based on HasTokenStore.

Copilot uses AI. Check for mistakes.
if (user) {
await user.signOut({ redirectUrl: options?.redirectUrl });
}
}

async getAuthHeaders(options?: { tokenStore?: TokenStoreInit }): Promise<{ "x-stack-auth": string }> {
return {
"x-stack-auth": JSON.stringify(await this.getAuthJson(options)),
};
}

async getAuthJson(options?: { tokenStore?: TokenStoreInit }): Promise<{ accessToken: string | null, refreshToken: string | null }> {
const user = await this.getUser({ tokenStore: options?.tokenStore ?? undefined as any });
Copy link

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The type assertion as any is used to bypass type checking. Consider using a more type-safe approach. This is the same issue as in the signOut method on line 2173.

Copilot uses AI. Check for mistakes.
if (user) {
await user.signOut(options);
return await user.getAuthJson();
}
return { accessToken: null, refreshToken: null };
}

async getProject(): Promise<Project> {
Expand Down
54 changes: 54 additions & 0 deletions packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -706,6 +706,60 @@ export class _StackServerAppImplIncomplete<HasTokenStore extends boolean, Projec
const providers = await this.listOAuthProviders();
return providers.find((p) => p.id === id) ?? null;
},
async registerPasskey(options?: { hostname?: string }): Promise<Result<undefined, KnownErrors["PasskeyRegistrationFailed"] | KnownErrors["PasskeyWebAuthnError"]>> {
// TODO remove duplicated code between this and the function in client-app-impl.ts
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

🧩 Analysis chain

Verify code duplication with client-app-impl.ts.

The TODO indicates duplicated code between this method and one in client-app-impl.ts. If significant portions are duplicated, consider extracting shared logic into a common utility function.

🏁 Script executed:

#!/bin/bash
# Check for similar registerPasskey implementation in client-app-impl.ts
rg -nP -A 50 'async registerPasskey\(' --type=ts -g 'client-app-impl.ts'

Length of output: 6394

The web search isn't helpful for this task. Let me search the codebase directly for the server version of registerPasskey.


---

🏁 Script executed:

```shell
#!/bin/bash
# Search for registerPasskey in server-app-impl.ts to see the actual server implementation
rg -nP -A 60 'async registerPasskey\(' --type=ts -g 'server-app-impl.ts'

Length of output: 8146

Extract duplicated passkey registration logic into shared utilities.

The TODO is valid. Both implementations share identical logic for hostname resolution, rpID override validation, and WebAuthn error handling. Consider extracting these into shared utility functions:

  • validateAndOverrideRpId() — handles sentinel validation and hostname substitution (lines 726–730 in server, 1470–1474 in client)
  • handleWebAuthnRegistrationError() — standardizes WebAuthn error handling (lines 733–746 in server, 1477–1487 in client)
  • resolveHostname() — centralizes hostname resolution (lines 711–714 in server, 1456–1459 in client)

The core difference—client using the existing session vs. server creating a temporary session—can be parameterized or handled by the caller, leaving the shared logic focused on credential generation and error handling.

🤖 Prompt for AI Agents 
packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts
around line 710: duplicate passkey registration logic exists in both
server-app-impl.ts and client-app-impl.ts (hostname resolution, rpID override
validation, and WebAuthn error handling). Extract three shared utility functions
into a common module (e.g., lib/auth/webauthn-utils.ts):
resolveHostname(hostnameOrSentinel) to centralize hostname resolution;
validateAndOverrideRpId(rpIdOverride, resolvedHostname) to perform sentinel
validation and return the effective rpId or throw; and
handleWebAuthnRegistrationError(err) to normalize and rethrow/log WebAuthn
errors. Replace the duplicated blocks in both server and client implementations
to call these utilities, and parameterize the remaining difference (session
creation vs. using existing session) by having the caller provide a session or a
session-creator callback so the shared code only handles credential generation
and error handling.

const hostname = options?.hostname || (await app._getCurrentUrl())?.hostname;
if (!hostname) {
throw new StackAssertionError("hostname must be provided if the Stack App does not have a redirect method");
}

// Use server interface to initiate passkey registration for this specific user
const initiationResult = await app._interface.initiateServerPasskeyRegistration(crud.id);

if (initiationResult.status !== "ok") {
return Result.error(new KnownErrors.PasskeyRegistrationFailed("Failed to get initiation options for passkey registration"));
}

const { options_json, code } = initiationResult.data;

// HACK: Override the rpID to be the actual domain
if (options_json.rp.id !== "THIS_VALUE_WILL_BE_REPLACED.example.com") {
throw new StackAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options_json.rp.id}`);
}

options_json.rp.id = hostname;

let attResp;
try {
const { startRegistration } = await import("@simplewebauthn/browser");
attResp = await startRegistration({ optionsJSON: options_json });
} catch (error: any) {
const { WebAuthnError } = await import("@simplewebauthn/browser");
if (error instanceof WebAuthnError) {
return Result.error(new KnownErrors.PasskeyWebAuthnError(error.message, error.name));
} else {
// This should never happen
const { captureError } = await import("@stackframe/stack-shared/dist/utils/errors");
captureError("passkey-registration-failed", error);
return Result.error(new KnownErrors.PasskeyRegistrationFailed("Failed to start passkey registration due to unknown error"));
}
}

// Create a temporary session to complete the registration
// TODO instead of creating a new session, this should just call the endpoint in a way in which it doesn't require a session
// (currently this shows up on session history etc... not ideal)
const { accessToken, refreshToken } = await app._interface.createServerUserSession(crud.id, 60000 * 2, false);
const tempSession = new InternalSession({
accessToken,
refreshToken,
refreshAccessTokenCallback: async () => null,
});

const registrationResult = await app._interface.registerPasskey({ credential: attResp, code }, tempSession);

await app._serverUserCache.refresh([crud.id]);
return registrationResult;
Comment on lines +748 to +761
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Double temporary session creation.

This method creates a second temporary session (in addition to the one created by initiateServerPasskeyRegistration), resulting in two session history entries for a single passkey registration. This compounds the concern noted in the TODO comment.

Consider refactoring both initiateServerPasskeyRegistration and the registration completion to use a single server-side flow that doesn't require user sessions, or reuse the initial temporary session for the completion step.

</comment_end>

🤖 Prompt for AI Agents 
packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts
lines 748-761: the code creates a second temporary session for completing
passkey registration which produces duplicate session history entries; instead
reuse the existing temporary session created by
initiateServerPasskeyRegistration (pass it through or return it from that
function) or change both initiation and completion to a server-side flow that
does not require a user session; update initiateServerPasskeyRegistration to
return the temp session (or a token object) and change this block to call
registerPasskey with that session rather than calling createServerUserSession
again, then remove the duplicate session creation and ensure
serverUserCache.refresh still receives the user id.

},
...app._createServerCustomer(crud.id, "user"),
} satisfies ServerUser;

Expand Down
3 changes: 2 additions & 1 deletion packages/template/src/lib/stack-app/apps/interfaces/client-app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { KnownErrors } from "@stackframe/stack-shared";
import { CurrentUserCrud } from "@stackframe/stack-shared/dist/interface/crud/current-user";
import { Result } from "@stackframe/stack-shared/dist/utils/results";
import { AsyncStoreProperty, GetCurrentPartialUserOptions, GetCurrentUserOptions, HandlerUrls, OAuthScopesOnSignIn, RedirectMethod, RedirectToOptions, TokenStoreInit, stackAppInternalsSymbol } from "../../common";
import { AsyncStoreProperty, AuthLike, GetCurrentPartialUserOptions, GetCurrentUserOptions, HandlerUrls, OAuthScopesOnSignIn, RedirectMethod, RedirectToOptions, TokenStoreInit, stackAppInternalsSymbol } from "../../common";
import { CustomerProductsList, CustomerProductsRequestOptions, Item } from "../../customers";
import { Project } from "../../projects";
import { ProjectCurrentUser, SyncedPartialUser, TokenPartialUser } from "../../users";
Expand Down Expand Up @@ -107,6 +107,7 @@ export type StackClientApp<HasTokenStore extends boolean = boolean, ProjectId ex
true
>
& { [K in `redirectTo${Capitalize<keyof Omit<HandlerUrls, 'handler' | 'oauthCallback'>>}`]: (options?: RedirectToOptions) => Promise<void> }
& AuthLike<HasTokenStore extends false ? { tokenStore: TokenStoreInit } : { tokenStore?: TokenStoreInit }>
);
export type StackClientAppConstructor = {
new <
Expand Down
Loading