apps/backend/src/lib/payments.tsx (2)

3-3: Use a type-only import for PrismaClientTransaction to avoid a runtime edge/cycle.

PrismaClientTransaction is only used as a type (in the options parameter). Importing it as a value can introduce unnecessary runtime coupling and increases the risk of circular deps during bundling. Switch to a type-only import.

-import { PrismaClientTransaction } from "@/prisma-client";
+import type { PrismaClientTransaction } from "@/prisma-client";

---

7-7: Deep import is fine, but consider reducing coupling to internal paths.

If SUPPORTED_CURRENCIES is (or can be) re‑exported from a stable top-level entry in @stackframe/stack-shared, prefer importing from there to avoid churn when internal paths change. If no stable entry exists, keeping the deep path is acceptable for now.

If a top-level export exists, update this line accordingly across the codebase. I can script a quick sweep to propose a single commit that standardizes this import.

apps/backend/prisma/seed.ts (1)

170-177: Review of “team_admin” permission addition: ✔️ Verified

I’ve confirmed that the new "$remove_members" permission is fully defined, used, and tested—no dangling references remain.

• Definition

• Declared in packages/stack-shared/src/schema-fields.ts and in the system permission map at apps/backend/src/lib/permissions.tsx
• Included in the team-scoped policy checks in team-memberships and team-invitations CRUD handlers

• Usage & UI gating

• UI component gating via user.usePermission(..., '$remove_members') in team-member-invitation-section.tsx
• API client/server methods enforce the permission in removeServerUserFromTeam and invitation-revocation paths

• E2E test coverage

• Negative case: team member without $remove_members is rejected (HTTP 403, TEAM_PERMISSION_REQUIRED)
• Positive case: team admin (with $remove_members) can delete a membership (HTTP 200) and emits the team_membership.deleted event

• Seed synchronization

• Only one team_admin seed exists in apps/backend/prisma/seed.ts; no other divergent definitions found.

Optional refactor: extract the ["$read_members","$remove_members","$update_team"] array into a const TEAM_ADMIN_PERMISSIONS to avoid string drift across seeds.

package.json (1)

21-21: Pin cmux to a fixed version for reproducible builds

To avoid inadvertently pulling in breaking changes or malicious updates, replace the unpinned npx -y cmux@latest invocation with a locally installed, version-pinned dependency:

• package.json (“scripts” section)

   "cmux": "pnpm pre && npx -y cmux@latest",

becomes

-  "cmux": "pnpm pre && npx -y cmux@latest",
+  "cmux": "pnpm pre && pnpm cmux",

• package.json (“devDependencies” section)
Add the latest stable cmux release (0.2.39):

   "devDependencies": {
+  "cmux": "0.2.39",
    "@changesets/cli": "^2.27.9",
    …
   },

This ensures builds use a known, audited version (0.2.39) rather than whatever lands next in the registry.

packages/template/src/lib/stack-app/teams/index.ts (1)

96-103: Document the new option for clarity at call sites.

Add a short TSDoc so callers know the default and how it maps to the API.

 export type ServerListUsersOptions = {
   cursor?: string,
   limit?: number,
   orderBy?: 'signedUpAt',
   desc?: boolean,
   query?: string,
+  /**
+   * When true, include anonymous users in the result set.
+   * Maps to GET /users?include_anonymous=true. Default: false (anonymous users excluded).
+   */
   includeAnonymous?: boolean,
 };

packages/stack-shared/src/interface/server-interface.ts (1)

220-227: Type surface looks good; add inline docs for includeAnonymous.

This keeps the boolean at the interface layer and converts to the expected string flag at the boundary. Recommend documenting the default/behavior.

   async listServerUsers(options: {
     cursor?: string,
     limit?: number,
     orderBy?: 'signedUpAt',
     desc?: boolean,
     query?: string,
+    /**
+     * Include anonymous users when true (adds `include_anonymous=true` to the query).
+     * Default: false (anonymous users excluded).
+     */
     includeAnonymous?: boolean,
   }): Promise<UsersCrud['Server']['List']> {

CLAUDE.md (2)

75-76: Wording + command consistency: use “ask” (not “tell”) and prefer pnpm codegen over pnpm run codegen.

Small editorial/nit improvements for tone and consistency with the “Extra commands” section.

- Sometimes, the typecheck will give errors along the line of "Cannot assign Buffer to Uint8Array" or similar, on changes that are completely unrelated to your own changes. If that happens, stop and tell the user to run `pnpm clean && pnpm i && pnpm run codegen && pnpm build:packages`, and restart the dev server (you cannot run this yourself). After that's done, the typecheck should pass.
+ Sometimes, the typecheck will give errors along the lines of "Cannot assign Buffer to Uint8Array" or similar, on changes that are completely unrelated to your own changes. If that happens, stop and ask the user to run `pnpm clean && pnpm i && pnpm codegen && pnpm build:packages`, and restart the dev server (you cannot run this yourself). After that's done, the typecheck should pass.

---

81-83: Testing guidance LGTM, optional enhancement: reference anonymous-user E2E coverage.

The snapshot-testing reminder is good. Consider adding a one-liner to point to the new anonymous E2E suites so folks mirror patterns when extending tests.

packages/stack-shared/src/known-errors.tsx (1)

734-742: Header-name casing consistency with other errors.

Elsewhere in KnownErrors we reference headers in lowercase (e.g., “x-stack-access-type”). To stay consistent and avoid confusion, suggest lowercasing the new header names in the message. Behavior is case-insensitive on the wire, this is just docs/UX consistency.

-    "X-Stack-Access-Token is for an anonymous user, but anonymous users are not enabled. Set the X-Stack-Allow-Anonymous-User header of this request to 'true' to allow anonymous users.",
+    "x-stack-access-token is for an anonymous user, but anonymous users are not enabled. Set the x-stack-allow-anonymous-user header of this request to 'true' to allow anonymous users.",

apps/dashboard/src/components/data-table/user-table.tsx (3)

9-9: Import style nit: prefer named hooks over React.useEffect.

To match prevailing style in the file, import useEffect directly and drop the default React import, or consistently use React.useEffect everywhere.

-import React, { useState } from "react";
+import { useEffect, useState } from "react";

And below:

-  React.useEffect(() => {
+  useEffect(() => {

---

120-126: Use a shared Badge component for the “Anonymous” chip.

For consistency with the design system (and future theming), prefer the library’s badge component over a custom-styled span.

-        {row.original.isAnonymous && <span className="px-2 py-0.5 text-xs bg-gray-100 text-gray-600 rounded">Anonymous</span>}
+        {row.original.isAnonymous && <BadgeCell badges={["Anonymous"]} />}

If BadgeCell doesn’t fit inside TextCell well, introduce a small Badge from stack-ui if available, or wrap BadgeCell with width constraints.

---

176-181: Include passkey in authTypes (optional).

If passkeys are a supported method in this UI, reflect it in authTypes for non-anonymous users to keep the table informative.

-    authTypes: user.isAnonymous ? ["anonymous"] : [
+    authTypes: user.isAnonymous ? ["anonymous"] : [
       ...user.otpAuthEnabled ? ["otp"] : [],
       ...user.hasPassword ? ["password"] : [],
+      ...user.passkeyAuthEnabled ? ["passkey"] : [],
       ...user.oauthProviders.map(p => p.id),
     ],

apps/backend/src/app/api/latest/users/crud.tsx (2)

382-388: Unused parameter in onRead.

query is destructured but unused. Remove to reduce noise unless required by a common handler signature.

-  onRead: async ({ auth, params, query }) => {
+  onRead: async ({ auth, params }) => {

---

439-440: Sorting direction parsing is correct; consider defaulting desc to true to align with UI (optional).

The UI defaults to signedUpAt desc; server defaults asc when desc is omitted. Not a bug, but you could set a server default to match the dashboard, reducing boilerplate on clients.

packages/stack-shared/src/utils/jwt.tsx (1)

98-104: Consider removing legacy key support in production

The code still prioritizes the legacy key format for backward compatibility. Consider setting a timeline for deprecation and eventual removal.

The TODO comment on line 99 indicates this is temporary. Do you want me to:

1. Create an issue to track the deprecation timeline?
2. Add environment-based feature flags to control legacy key support?
3. Generate migration documentation for existing deployments?

apps/backend/src/oauth/model.tsx (1)

14-20: Empty interface declaration seems unnecessary

The empty User interface doesn't provide any type information or functionality.

Consider either:

1. Adding relevant properties to the interface if needed for type safety
2. Removing it if it's not being used
3. Adding a comment explaining why it's empty (e.g., for future extensibility)

apps/backend/src/app/api/latest/integrations/idp.ts (2)

241-247: Add cache headers for JWKS to reduce load and improve client performance

JWKS rotates infrequently. Consider adding Cache-Control (and optionally ETag) so SDKs and IdPs can cache aggressively.

Apply this diff:

   middleware(async (ctx, next) => {
     if (ctx.path === '/.well-known/jwks.json') {
       ctx.body = publicJwkSet;
       ctx.type = 'application/json';
+      ctx.set('Cache-Control', 'public, max-age=300, stale-while-revalidate=86400');
       return;
     }
     await next();
   });

---

165-173: Confirm signing key precedence if multiple private keys are returned

getPrivateJwks currently returns an array that includes a legacy key first (per the TODO in the shared util). oidc-provider may prefer the first usable key as the default signer. If you intend the newer key to be primary, explicitly order the array or filter out the legacy one once safe to do so.

If helpful, I can open a follow-up to invert/sort keys by intended precedence once the TODO lands.

apps/backend/src/route-handlers/smart-request.tsx (1)

173-173: Be tolerant when parsing the anonymous header

Header parsing is strict equality to "true". Consider accepting "1", "True", etc., to reduce integration friction.

Apply this diff:

-  const allowAnonymousUser = req.headers.get("x-stack-allow-anonymous-user") === "true";
+  const allowAnonymousUser = /^(true|1)$/i.test(req.headers.get("x-stack-allow-anonymous-user") ?? "");

apps/backend/src/lib/users.tsx (1)

1-30: Solid abstraction; consider minor type/ergonomics tweaks

The upgrade-or-create helper is clean and correctly toggles is_anonymous to false on upgrade. Two small improvements:

• Make allowedErrorTypes optional with a default to [] to reduce call-site noise.
• Type allowedErrorTypes as KnownError constructors for stronger typing.

Apply this diff:

-import { UsersCrud } from "@stackframe/stack-shared/dist/interface/crud/users";
+import { UsersCrud } from "@stackframe/stack-shared/dist/interface/crud/users";
+import { KnownError } from "@stackframe/stack-shared";

 export async function createOrUpgradeAnonymousUser(
   tenancy: Tenancy,
   currentUser: UsersCrud["Admin"]["Read"] | null,
   createOrUpdate: UsersCrud["Admin"]["Create"] & UsersCrud["Admin"]["Update"],
-  allowedErrorTypes: (new (...args: any) => any)[],
+  allowedErrorTypes: (new (...args: any[]) => KnownError)[] = [],
 ): Promise<UsersCrud["Admin"]["Read"]> {

apps/backend/src/app/api/latest/auth/oauth/authorize/[provider_id]/route.tsx (2)

74-76: Good validation for link flow; consider using a KnownError for consistency

The 400 check is correct and prevents ambiguous link attempts. For consistency with the rest of the API (x-stack-known-error header), prefer a KnownErrors-based error if one exists for missing/invalid query parameters.

---

100-108: Minor: defensive extraScope assignment

Once the unconditional gating above is applied, consider passing extraScope only when present to avoid provider-specific surprises.

-    const oauthUrl = providerObj.getAuthorizationUrl({
+    const oauthUrl = providerObj.getAuthorizationUrl({
       codeVerifier: innerCodeVerifier,
       state: innerState,
-      extraScope: query.provider_scope,
+      ...(query.provider_scope ? { extraScope: query.provider_scope } : {}),
     });

apps/backend/src/app/api/latest/projects-anonymous-users/[project_id]/.well-known/[...route].ts (2)

17-21: Make pathname rewrite segment-safe

Using a raw string replace can unexpectedly rewrite unrelated portions of the path if “projects-anonymous-users” appears elsewhere. Prefer a segment-aware replacement.

-    url.pathname = url.pathname.replace("projects-anonymous-users", "projects");
+    const parts = url.pathname.split("/");
+    const idx = parts.indexOf("projects-anonymous-users");
+    if (idx !== -1) parts[idx] = "projects";
+    url.pathname = parts.join("/");

---

24-28: Consider exporting HEAD and OPTIONS, too

Some clients probe these discovery endpoints with HEAD/OPTIONS. Exporting them to the same handler keeps behavior uniform.

 export const GET = handler;
 export const POST = handler;
 export const PUT = handler;
 export const PATCH = handler;
 export const DELETE = handler;
+export const HEAD = handler;
+export const OPTIONS = handler;

apps/backend/src/app/api/latest/auth/password/sign-up/route.tsx (1)

53-63: Happy path LGTM; minor thought on allowed errors

Including UserWithEmailAlreadyExists makes sense. If you expect other collisions (e.g., primary email already verified by another flow), consider extending allowedErrorTypes accordingly. Otherwise, this is good.

apps/backend/src/lib/tokens.tsx (4)

86-88: Avoid logging raw access tokens

Logging full JWTs is sensitive. Redact before logging to reduce PII risk.

-        console.warn("Unparsable access token. This might be a user error, but if it happens frequently, it's a sign of a misconfiguration.", { accessToken, error });
+        const redact = (t: string) => (t.length <= 16 ? "<redacted>" : `${t.slice(0, 12)}…${t.slice(-6)}`);
+        console.warn(
+          "Unparsable access token. This might be a user error, but if it happens frequently, it's a sign of a misconfiguration.",
+          { token: redact(accessToken), error }
+        );

---

92-99: Fix inverted log messages for audience/role mismatch

The messages describe the opposite condition. Correct them to match the predicate to avoid debugging confusion.

-    if (aud.endsWith(":anon") && !isAnonymous) {
-      console.warn("Unparsable access token. Role is set to anon, but audience is not an anonymous audience.", { accessToken, payload });
+    if (aud.endsWith(":anon") && !isAnonymous) {
+      console.warn("Unparsable access token. Audience is anonymous (:anon) but role is not 'anon'.", { payloadAud: aud, payload });
       return Result.error(new KnownErrors.UnparsableAccessToken());
     } else if (!aud.endsWith(":anon") && isAnonymous) {
-      console.warn("Unparsable access token. Audience is not an anonymous audience, but role is set to anon.", { accessToken, payload });
+      console.warn("Unparsable access token. Audience is not anonymous but role is 'anon'.", { payloadAud: aud, payload });
       return Result.error(new KnownErrors.UnparsableAccessToken());
     }

---

57-63: Optional: de-duplicate keys in JWKS output by kid

Combining per-audience fallback and current keys can yield duplicates across rotations. Consider stable de-duplication by kid to keep JWKS minimal.

 export async function getPublicProjectJwkSet(projectId: string, allowAnonymous: boolean) {
-  const privateJwks = [
+  const privateJwksAll = [
     ...await getPrivateJwks({ audience: getAudience(projectId, false) }),
     ...allowAnonymous ? await getPrivateJwks({ audience: getAudience(projectId, true) }) : [],
   ];
-  return await getPublicJwkSet(privateJwks);
+  const byKid = new Map(privateJwksAll.map(j => [j.kid, j]));
+  return await getPublicJwkSet([...byKid.values()]);
 }

---

101-109: Minor: reuse computed isAnonymous

You already compute isAnonymous above; reuse it to avoid double checks.

-    const result = await accessTokenSchema.validate({
-      projectId: aud.split(":")[0],
-      userId: payload.sub,
-      branchId: payload.branchId,
-      refreshTokenId: payload.refreshTokenId,
-      exp: payload.exp,
-      isAnonymous: payload.role === 'anon',
-    });
+    const result = await accessTokenSchema.validate({
+      projectId: aud.split(":")[0],
+      userId: payload.sub,
+      branchId: payload.branchId,
+      refreshTokenId: payload.refreshTokenId,
+      exp: payload.exp,
+      isAnonymous,
+    });

apps/backend/src/app/api/latest/projects/[project_id]/.well-known/jwks.json/route.ts (4)

20-22: Parse include_anonymous as a boolean to be more robust (accept true/false, 1/0, yes/no).

Right now the query schema forces a lowercase string "true"/"false". This is brittle and will reject common variants. Prefer a boolean schema with a safe transform and use a boolean in the handler.

Apply this diff:

-import { yupArray, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
+import { yupArray, yupBoolean, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
@@
-    query: yupObject({
-      include_anonymous: yupString().oneOf(["true", "false"]).default("false"),
-    }),
+    query: yupObject({
+      include_anonymous: yupBoolean()
+        .transform((v, o) => {
+          if (typeof o === "string") {
+            const s = o.trim().toLowerCase();
+            return s === "true" || s === "1" || s === "yes";
+          }
+          return !!v;
+        })
+        .default(false),
+    }),
@@
-  async handler({ params, query }) {
+  async handler({ params, query }) {
@@
-      body: await getPublicProjectJwkSet(params.project_id, query.include_anonymous === "true"),
+      body: await getPublicProjectJwkSet(params.project_id, !!query.include_anonymous),

Also applies to: 31-31, 41-41

---

31-36: Consider gating anonymous JWKS on project configuration to avoid misleading exposure.

Today, include_anonymous=true will expose anon keys irrespective of whether the project has anonymous users enabled. If projects can disable anonymous auth, returning anon keys could confuse integrators. Gate the inclusion on the project’s config (e.g., project.settings.allowAnonymous) in addition to the query flag.

Example:

-  async handler({ params, query }) {
+  async handler({ params, query }) {
     const project = await getProject(params.project_id);

     if (!project) {
       throw new StatusError(404, "Project not found");
     }

+    const allowAnonForProject = project.settings?.allowAnonymous === true;
+    const includeAnon = (query.include_anonymous === "true") && allowAnonForProject;
@@
-      body: await getPublicProjectJwkSet(params.project_id, query.include_anonymous === "true"),
+      body: await getPublicProjectJwkSet(params.project_id, includeAnon),

If no such setting exists, ignore this suggestion.

---

9-15: Confirmed: JWKS endpoint is public and include_anonymous schema matches intended behavior

• The GET handler at
  apps/backend/src/app/api/latest/projects/[project_id]/.well-known/jwks.json/route.ts
  is defined with createSmartRouteHandler({ … }) and has no authentication middleware or requireAuth setting, so it’s publicly accessible as expected for a JWKS endpoint.
• The query parameter include_anonymous is defined as

  include_anonymous: yupString()
    .oneOf(["true", "false"])
    .default("false"),

  which produces an OpenAPI parameter of type string with enum ["true","false"] and default "false". The handler internally checks query.include_anonymous === "true" to include anonymous keys.

Optional refinement (nit): if you’d prefer to expose include_anonymous as a true boolean in the OpenAPI spec and SDKs, you could switch to yupBoolean().default(false) (or add a transform) so that clients see type boolean instead of a string enum.

---

38-42: Add RFC-7517 media type and cache headers to the JWKS route

I verified that createSmartRouteHandler handlers can include a headers field on the returned object, since SmartResponse defines an optional
headers?: Record<string,string[]> and createResponse merges obj.headers into the HTTP response (see createResponse in smart-response.tsx).

Apply this optional refactor to improve interoperability and performance:

• File: apps/backend/src/app/api/latest/projects/[project_id]/.well-known/jwks.json/route.ts
• Around lines 38–42, update the return value as follows:

     return {
       statusCode: 200,
       bodyType: "json",
+      headers: {
+        // RFC-7517 JWKS media type
+        "content-type": "application/jwk-set+json",
+        // public cache for 5 minutes, revalidate in background up to 24 h
+        "cache-control": "public, max-age=300, stale-while-revalidate=86400",
+      },
       body: await getPublicProjectJwkSet(
         params.project_id,
         query.include_anonymous === "true"
       ),
     };

.claude/CLAUDE-KNOWLEDGE.md (6)

6-14: Tighten wording and casing; avoid brittle implementation specifics.

• Use consistent casing for the DB field vs. runtime property (is_anonymous in DB, user.isAnonymous in code), and avoid implying both simultaneously without context.
• “prefixed with "anon-" in the generation” → “prefixed with "anon-" during generation”.
• Mentioning exact internals (e.g., role: 'anon' claim and passing isAnonymous flags) is fine, but note that names may change; consider clarifying they are implementation details.

Apply this editorial diff:

-Anonymous users are a special type of user that can be created without any authentication. They have `isAnonymous: true` in the database and use different JWT signing keys with a `role: 'anon'` claim. Anonymous JWTs use a prefixed secret ("anon-" + audience) for signing and verification.
+Anonymous users are a special type of user that can be created without any authentication. In the database they use `is_anonymous: true` (exposed in code as `user.isAnonymous`). Their JWTs are signed with audience-specific keys and include a role indicating anonymity (e.g., `role: 'anon'`). Anonymous JWTs use a secret derived with an "anon-" prefix combined with the audience for signing and verification.

---

15-17: Header naming and default behavior: make claims precise and consistent.

• Use a single canonical header spelling: X-Stack-Allow-Anonymous-User (header names are case-insensitive).
• “default for client SDK calls” may drift across SDKs. Prefer “SDKs that support anonymous access set this header to true by default” or document SDK-specific behavior.

Apply:

-A: This header controls whether anonymous users are allowed to access an endpoint. When set to "true" (which is the default for client SDK calls), anonymous JWTs are accepted. When false or missing, anonymous users get an `AnonymousAuthenticationNotAllowed` error.
+A: This header controls whether anonymous users are allowed to access an endpoint. When set to "true", anonymous JWTs are accepted. When false or missing, anonymous users get an `AnonymousAuthenticationNotAllowed` error. Some client SDKs set this header to "true" by default when anonymous access is enabled.

And elsewhere:

-- Sets `x-stack-allow-anonymous-user: "true"` for client access type
+- Sets `X-Stack-Allow-Anonymous-User: "true"` for client access type

Also applies to: 52-55

---

19-23: Align field casing when describing the upgrade flow.

The bullets mix is_anonymous and camelCase elsewhere. Prefer explicitly noting DB vs. code property to prevent confusion in future PRs and test assertions.

Apply:

-1. Setting `is_anonymous: false`
+1. Setting `is_anonymous: false` (DB; exposed as `user.isAnonymous = false` in code)

---

38-42: Add media type and caching note for JWKS consumers.

Since you’ve documented include_anonymous here, add a note that the endpoint returns application/jwk-set+json and may be cached for a short period (e.g., 5–10 minutes). This helps integrators configure verifiers correctly.

Proposed addition after the bullet list:

+- The response media type is `application/jwk-set+json`. Clients can safely cache JWKS for a short period (e.g., 5–10 minutes) and refresh on key ID (kid) mismatch.

---

69-80: Avoid over-specifying kid/derivation internals to reduce future churn.

Documenting “takes only first 12 characters of hash” and similar details invites drift. Consider wording this as an opaque, stable identifier derived from secret material, without length specifics.

Proposed rewrite:

-2. **Kid Generation**: `getKid()` creates a key ID from:
-   - Base secret (STACK_SERVER_SECRET) 
-   - "kid" string with optional "anon-" prefix
-   - Takes only first 12 characters of hash
+2. **Key ID (kid) Generation**: A deterministic key identifier is derived from secret material and flags (including the anonymous prefix). Treat the exact derivation as an internal detail.

---

96-102: Remove duplicate section; content already covered above.

“What makes anonymous JWTs different...” repeats information from the earlier section. Consolidate to avoid drift.

Apply this diff to delete the duplicate block:

-## Q: What makes anonymous JWTs different from regular JWTs?
-A: Anonymous JWTs have:
-1. **Different derived secret**: Uses "anon-" prefix in secret derivation
-2. **Different kid**: Uses "anon-" prefix resulting in different key ID
-3. **Role field**: Contains `role: 'anon'` in the payload
-4. **Verification requirements**: Requires `allowAnonymous: true` flag to be verified
-

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: CR
PR: stack-auth/stack-auth#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-04T22:25:51.260Z
Learning: Applies to apps/backend/src/app/api/latest/**/* : The project uses a custom route handler system in the backend for consistent API responses

apps/e2e/tests/backend/endpoints/api/v1/auth/anonymous/anonymous-comprehensive.test.ts (2)

85-92: Test rejection by omitting the header, not by setting it to "false"

The absence of X-Stack-Allow-Anonymous-User is the intended rejection path. Setting it to "false" is confusing and couples the test to a specific implementation detail of the header parser.

Apply this diff:

-  // Try to access an endpoint without the header (niceBackendFetch adds it by default unless explicitly set to false)
+  // Try to access an endpoint without the header (niceBackendFetch adds it by default; override with `undefined` to omit)
   const res = await niceBackendFetch("/api/v1/users/me", {
     accessType: "client",
     headers: {
       "x-stack-access-token": accessToken,
-      "x-stack-allow-anonymous-user": "false",
+      "x-stack-allow-anonymous-user": undefined as any,
     },
   });

---

50-74: Make JWKS assertions robust against additional/rotated keys

Exact array lengths and unique count assertions are brittle because multiple keys per audience (legacy + rotated/current) may exist. Assert relative properties and set relationships instead.

Apply this diff:

-  const regularKeys = regularJwks.body.keys;
-  expect(regularKeys).toHaveLength(2);
+  const regularKeys = regularJwks.body.keys;
+  expect(Array.isArray(regularKeys)).toBe(true);
+  expect(regularKeys.length).toBeGreaterThanOrEqual(1);

@@
-  const allKeys = anonymousJwks.body.keys;
-  expect(allKeys).toHaveLength(4);
+  const allKeys = anonymousJwks.body.keys;
+  expect(Array.isArray(allKeys)).toBe(true);
+  expect(allKeys.length).toBeGreaterThan(regularKeys.length);

@@
-  const kids = allKeys.map((key: any) => key.kid);
-  expect(new Set(kids).size).toBe(4);
+  const regularKids = new Set(regularKeys.map((k: any) => k.kid));
+  const allKids = new Set(allKeys.map((k: any) => k.kid));
+  // anonymous-inclusive set must be a strict superset of regular keys
+  for (const kid of regularKids) expect(allKids.has(kid)).toBe(true);
+  expect(allKids.size).toBeGreaterThan(regularKids.size);

packages/stack-shared/src/utils/jwt.tsx (1)

10-17: getStackServerSecret returns decoded bytes, breaking key derivation stability

Returning jose.base64url.decode(STACK_SERVER_SECRET) changes the type and the serialized value used by JSON.stringify([...]) in downstream hash inputs. This silently breaks backwards compatibility with old key derivations (including oldGetPerAudienceSecret) and will invalidate existing KIDs and JWKS expectations.

Return the validated base64url string instead (validate by decoding, but return the string):

-function getStackServerSecret() {
-  const STACK_SERVER_SECRET = process.env.STACK_SERVER_SECRET ?? "";
-  try {
-    return jose.base64url.decode(STACK_SERVER_SECRET);
-  } catch (e) {
-    throw new StackAssertionError("STACK_SERVER_SECRET is not valid. Please use the generateKeys script to generate a new secret.", { cause: e });
-  }
-}
+function getStackServerSecret(): string {
+  const STACK_SERVER_SECRET = process.env.STACK_SERVER_SECRET ?? "";
+  try {
+    // Validate format; ignore returned bytes
+    jose.base64url.decode(STACK_SERVER_SECRET);
+  } catch (e) {
+    throw new StackAssertionError("STACK_SERVER_SECRET is not valid. Please use the generateKeys script to generate a new secret.", { cause: e });
+  }
+  return STACK_SERVER_SECRET;
+}

apps/backend/src/lib/tokens.tsx (2)

86-88: Stop logging full access tokens in warnings; this is sensitive data

Logging the raw accessToken can leak credentials to logs/observability systems.

-        console.warn("Unparsable access token. This might be a user error, but if it happens frequently, it's a sign of a misconfiguration.", { accessToken, error });
+        console.warn("Unparsable access token. This might be a user error, but if it happens frequently, it's a sign of a misconfiguration.", { token_preview: `${accessToken.slice(0, 6)}…${accessToken.slice(-4)}`, error: String(error) });

If you prefer, drop the token entirely. Apply the same masking logic anywhere else tokens are logged.

---

92-99: Fix swapped warning message and avoid leaking token/payload

The first branch checks “audience is anonymous but role is not anon”, yet the message says the opposite. Also avoid logging full token/payload.

-    if (aud.endsWith(":anon") && !isAnonymous) {
-      console.warn("Unparsable access token. Role is set to anon, but audience is not an anonymous audience.", { accessToken, payload });
+    if (aud.endsWith(":anon") && !isAnonymous) {
+      console.warn("Unparsable access token: audience is anonymous (:anon) but role is not 'anon'.");
       return Result.error(new KnownErrors.UnparsableAccessToken());
-    } else if (!aud.endsWith(":anon") && isAnonymous) {
-      console.warn("Unparsable access token. Audience is not an anonymous audience, but role is set to anon.", { accessToken, payload });
+    } else if (!aud.endsWith(":anon") && isAnonymous) {
+      console.warn("Unparsable access token: audience is non-anonymous but role is 'anon'.");
       return Result.error(new KnownErrors.UnparsableAccessToken());
     }

apps/e2e/tests/backend/endpoints/api/v1/auth/anonymous/sign-up.test.ts (2)

8-10: Redundant per-call header — already injected by helper

niceBackendFetch sets x-stack-allow-anonymous-user by default. The extra headers block is unnecessary; consider removing to centralize behavior in one place. If you adopt the opt-out suggested in backend-helpers, keep per-call headers only where you explicitly need to override.

Apply this diff:

-  const me = await niceBackendFetch("/api/v1/users/me", {
-    accessType: "client",
-    headers: {
-      "x-stack-allow-anonymous-user": "true",
-    },
-  });
+  const me = await niceBackendFetch("/api/v1/users/me", {
+    accessType: "client",
+  });

---

39-56: Behavioral change test — now correctly expects success and tokens

The test title and assertions match the new “unrestricted anon sign-up” behavior. Consider adding a companion negative test that sets allowAnonymousHeader: false to assert AnonymousAuthenticationNotAllowed.

Example:

const res = await niceBackendFetch("/api/v1/auth/anonymous/sign-up", {
  method: "POST",
  accessType: "client",
  allowAnonymousHeader: false,
});
expect(res.status).toBe(401);
expect(res.headers.get("x-stack-known-error")).toBe("ANONYMOUS_AUTHENTICATION_NOT_ALLOWED");

apps/e2e/tests/backend/endpoints/api/v1/auth/anonymous/anonymous-upgrade.test.ts (3)

95-129: Confirming old anon token behavior post-upgrade — double-check intended policy

Test asserts old anon token remains usable after upgrade (now reflecting non-anon state). If that’s the intended policy, keep this; otherwise, consider asserting that anon tokens lose privileged capabilities post-upgrade. At minimum, add one endpoint check that requires authenticated role (not just identity) to ensure role-based gating stays correct.

---

140-156: Minor: prefer direct status assertions over inline numeric snapshots

Use expect(secondSignUpRes.status).toBe(200) for readability and to avoid brittle snapshots for simple scalars.

Apply this diff:

- expect(secondSignUpRes.status).toBe(200);
+ expect(secondSignUpRes.status).toBe(200);

(Note: keep using snapshot for structured bodies where it adds value.)

---

448-449: Minor: status code assertion as snapshot

Prefer expect(upgradeRes.status).toBe(409) over snapshotting a single number.

Apply this diff:

- expect(upgradeRes.status).toMatchInlineSnapshot(`409`);
+ expect(upgradeRes.status).toBe(409);

apps/e2e/tests/backend/endpoints/api/v1/auth/anonymous/anonymous-comprehensive.test.ts (2)

10-20: Prefer property-based assertions over inline snapshot for tokens

Inline snapshotting the full NiceResponse object is noisy and brittle. Assert just the contract (status 200 and presence/shape of fields).

Example:

-  expect(res).toMatchInlineSnapshot(`
-    NiceResponse { ... }
-  `);
+  expect(res.status).toBe(200);
+  expect(typeof res.body.access_token).toBe("string");
+  expect(typeof res.body.refresh_token).toBe("string");
+  expect(typeof res.body.user_id).toBe("string");

---

23-48: Small hardening: also assert JWT has a kid and the payload has an aud/iss

You already check role and kid presence; adding basic audience/issuer presence helps catch mis-issuance without overfitting.

Example:

   expect(payload.role).toBe('anon');
   expect(header.kid).toBeTruthy();
+  expect(typeof payload.aud).toBe("string");
+  expect(typeof payload.iss).toBe("string");

packages/stack-shared/src/utils/jwt.tsx (2)

61-78: Avoid mixing WebCrypto and Node crypto for the same hash

getPrivateJwkFromDerivedSecret uses globalVar.crypto.subtle.digest, while surrounding code uses Node’s crypto.createHash. Mixing implementations can introduce subtle environment differences. Prefer Node crypto.createHash("sha256") for consistency server-side.

Example:

-  const secretHash = await globalVar.crypto.subtle.digest("SHA-256", jose.base64url.decode(derivedSecret));
-  const priv = new Uint8Array(secretHash);
+  const priv = crypto.createHash("sha256").update(jose.base64url.decode(derivedSecret)).digest();

---

37-49: Verify uses aud from unverified JWT; guard against pathological inputs

Decoding aud without bounds can lead to large-audience DoS vectors (huge base64 token causing expensive derivation). Add a sanity limit on token length before deriving JWKS.

Example:

-  const decodedJwt = jose.decodeJwt(options.jwt);
+  if (options.jwt.length > 10_000) throw new JOSEError("JWT too large");
+  const decodedJwt = jose.decodeJwt(options.jwt);

apps/backend/src/lib/users.tsx (1)

10-11: Make allowedErrorTypes optional with a default

Most call sites pass []. Defaulting this param reduces boilerplate and avoids accidental undefined.

-export async function createOrUpgradeAnonymousUser(
+export async function createOrUpgradeAnonymousUser(
   tenancy: Tenancy,
   currentUser: UsersCrud["Admin"]["Read"] | null,
   createOrUpdate: KeyIntersect<UsersCrud["Admin"]["Create"], UsersCrud["Admin"]["Update"]>,
-  allowedErrorTypes: (new (...args: any) => any)[],
+  allowedErrorTypes: (new (...args: any) => any)[] = [],
 ): Promise<UsersCrud["Admin"]["Read"]> {

apps/backend/src/app/api/latest/auth/oauth/callback/[provider_id]/route.tsx (1)

356-391: Consider atomicity: wrap user upgrade + authMethod + oauthAccount in one transaction

createOrUpgradeAnonymousUser (internally transactional) is followed by separate authMethod and projectUserOAuthAccount writes. If the latter fail, you can end up with a created/upgraded user without an OAuth linkage, making retries and reconciliation messy.

Approach: add an internal handler (or extend adminCreate/adminUpdate) that performs “create/upgrade + create authMethod + create oauth account + store tokens” in a single Prisma transaction. If refactoring now is too risky, at least catch unique/constraint errors and roll back by deleting the user when appropriate.

Sketch:

await prisma.$transaction(async (tx) => {
  const account = await createOrUpgradeAnonymousUser(tenancy, currentUser, data, []);
  const authMethod = await tx.authMethod.create({ data: { tenancyId: tenancy.id, projectUserId: account.id } });
  const oauthAccount = await tx.projectUserOAuthAccount.create({
    data: {
      tenancyId: tenancy.id,
      projectUserId: account.id,
      configOAuthProviderId: provider.id,
      providerAccountId: userInfo.accountId,
      email: userInfo.email,
      oauthAuthMethod: { create: { authMethodId: authMethod.id } },
      allowConnectedAccounts: true,
      allowSignIn: true,
    },
  });
  await storeTokens(oauthAccount.id);
});

Note: Because createOrUpgradeAnonymousUser uses handlers with their own transactions, consider a sibling helper that accepts a tx and performs the equivalent logic inline to keep everything atomic.

examples/demo/src/app/anonymous-test/page.tsx (2)

9-11: Remove unused userNotAnonymous to avoid dead code and lint warnings

userNotAnonymous is never used; keeping it may trip no-unused-vars.

-  const userNotAnonymous = useUser();
-  const user = useUser({ or: "anonymous-if-exists" });
+  const user = useUser({ or: "anonymous-if-exists" });

---

16-28: Optionally record success for the signup test to surface positive feedback in the UI

Right now you only set testResults.signup on error, so the “Test Results” card never shows a success. If desired:

   const signUpAnonymously = async () => {
     setLoading('signup');
     try {
       await app.getUser({ or: "anonymous" });
+      setTestResults(prev => ({ ...prev, signup: { success: true, status: '200', data: { message: 'Signed up anonymously' } } }));
     } catch (error) {
       setTestResults(prev => ({
         ...prev,
         signup: { success: false, error: error instanceof Error ? error.message : 'Unknown error' }
       }));
     } finally {
       setLoading(null);
     }
   };

apps/backend/src/lib/tokens.tsx (1)

76-80: Avoid repeated aud.split(':')[0] parsing; compute once for clarity

Minor readability nit: extract projectId once and reuse.

-      payload = await verifyJWT({
-        allowedIssuers: [
-          getIssuer(aud.split(":")[0], false),
-          ...(allowAnonymous ? [getIssuer(aud.split(":")[0], true)] : []),
-        ],
-        jwt: accessToken,
-      });
+      const projectId = aud.split(":")[0]!;
+      payload = await verifyJWT({
+        allowedIssuers: [
+          getIssuer(projectId, false),
+          ...(allowAnonymous ? [getIssuer(projectId, true)] : []),
+        ],
+        jwt: accessToken,
+      });

packages/stack-shared/src/interface/client-interface.ts (1)

295-295: Header for anonymous access: OK to always send; optionally gate to reduce noise

Adding X-Stack-Allow-Anonymous-User: "true" to all client requests is safe (server-side can require it only for anon tokens). If you want to minimize header noise, you could conditionally include it only when an access token is present.

No change required.

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (2)

321-323: Double assignment of _redirectMethod; ensure platform guard removes the non-applicable line

There are two consecutive assignments; the “nextjs” one overwrites the previous. If your platform filter retains both, behavior may be surprising outside Next.js. Suggest wrapping them in explicit platform guards or consolidating:

-    this._redirectMethod = _options.redirectMethod || "none";
-    this._redirectMethod = _options.redirectMethod || "nextjs"; // THIS_LINE_PLATFORM next
+    // Default to "nextjs" in Next, otherwise "none"
+    this._redirectMethod = _options.redirectMethod || ("nextjs" as RedirectMethod); // THIS_LINE_PLATFORM next
+    this._redirectMethod = _options.redirectMethod || "none"; // THIS_LINE_PLATFORM !next

---

1761-1766: MFA sign-in passes session consistently: LGTM; unify error checks

Minor consistency nit: elsewhere you use KnownErrors.InvalidTotpCode.isInstance(e). Use the same here to avoid cross-realm issues:

-      if (e instanceof KnownErrors.InvalidTotpCode) {
+      if (KnownErrors.InvalidTotpCode.isInstance(e)) {
         return Result.error(e);
       }

apps/backend/src/app/api/latest/users/crud.tsx (3)

48-56: Polish: handle possessives for names ending with “s”

Minor UX nit: "James's Team" vs "James' Team". If you care about style, consider trimming the extra “s” for names already ending with “s”.

Apply this refinement:

-  if (userDisplayName) {
-    return `${userDisplayName}'s Team`;
-  }
+  if (userDisplayName) {
+    const suffix = userDisplayName.endsWith('s') ? "'" : "'s";
+    return `${userDisplayName}${suffix} Team`;
+  }

Optional: using the full primary email in team names can surface PII in shared contexts. If that's a concern later, we can switch to the email local-part or a redacted form.

---

420-426: Confirm whether GET /users/:id should honor include_anonymous

onRead now accepts query but does not use it. If the intent is that anonymous users are excluded by default across “user endpoints” unless include_anonymous="true", this route currently returns anonymous users unconditionally.

If that’s intentional (List-only filter), ignore this. Otherwise, add a guard:

   onRead: async ({ auth, params, query }) => {
     const user = await getUser({ tenancyId: auth.tenancy.id, userId: params.user_id });
     if (!user) {
       throw new KnownErrors.UserNotFound();
     }
+    if (query?.include_anonymous !== 'true' && user.is_anonymous) {
+      // Match List semantics: hide anonymous unless explicitly requested
+      throw new KnownErrors.UserNotFound();
+    }
     return user;
   },

Would you like me to patch this behavior and extend tests to cover both read/list cases?

---

948-965: Scope the rename to the selected personal team to avoid accidental renames

Currently any team with displayName === "Personal Team" that the user belongs to will be renamed on anon→non-anon transitions. If a user created another team deliberately named "Personal Team", it would also be renamed.

Tighten the filter to only the selected team (which your creation code marks as selected), reducing collateral effects.

-        await tx.team.updateMany({
-          where: {
-            tenancyId: auth.tenancy.id,
-            teamMembers: {
-              some: {
-                projectUserId: params.user_id,
-              },
-            },
-            displayName: personalTeamDefaultDisplayName,
-          },
+        await tx.team.updateMany({
+          where: {
+            tenancyId: auth.tenancy.id,
+            teamMembers: {
+              some: {
+                projectUserId: params.user_id,
+                isSelected: BooleanTrue.TRUE,
+              },
+            },
+            displayName: personalTeamDefaultDisplayName,
+          },
           data: {
             displayName: getPersonalTeamDisplayName(data.display_name ?? null, data.primary_email ?? null),
           },
         });

If you want even stronger scoping, we can tag personal teams at creation (e.g., server_metadata.is_personal_team = true) and match on that flag instead of name.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

apps/backend/src/middleware.tsx (1)

33-34: Add CORS allowance for anonymous header — correct and sufficient

Allowing x-stack-allow-anonymous-user in Access-Control-Allow-Headers is required for browser clients; no further changes needed here.

apps/e2e/tests/backend/backend-helpers.ts (2)

582-596: Including token in OAuth authorize query — aligned with upgrade/linking flow

Passing token when present is correct and leverages filterUndefined to avoid noise. No changes requested.

---

836-842: Anonymous.signUp now returns tokens — good API for tests

Returning response, accessToken, refreshToken, and userId reduces boilerplate and keeps backendContext in sync. Looks good.

apps/e2e/tests/backend/endpoints/api/v1/users.test.ts (1)

1285-1303: Snapshot updates reflect new personal team naming for anon→non-anon transition

The change to display_name: null and selected_team.display_name: "Personal Team" is consistent with the new behavior. No action needed.

apps/e2e/tests/backend/endpoints/api/v1/auth/anonymous/anonymous-upgrade.test.ts (4)

13-44: Anon ‘me’ pre-check — coverage looks good

Validates anon payload shape before upgrade; assertions are appropriate.

---

327-367: OAuth upgrade path — assertions make sense

Verifies providers list and that anon token reflects upgraded state. LGTM.

---

372-421: Metadata preservation check — solid coverage

Server and client metadata persistence across upgrade is asserted correctly, including server-only readback via include_anonymous. Good use of urlString for safe query construction.

---

451-508: I’ve added a script to locate and print the relevant section of the test file so we can confirm whether a post-upgrade team-name assertion exists. Once you share the output, we can verify and rewrite the review comment accordingly.

packages/template/src/lib/auth.ts (3)

10-33: LGTM: session is now plumbed into OAuth URL generation

Forwarding session to iface.getOAuthUrl aligns with the updated client interface and preserves per-session context. Redirect flow remains unchanged.

---

35-59: LGTM: addNewOAuthProviderOrScope forwards session and after-callback URL

The link flow correctly includes session and afterCallbackRedirectUrl, matching the new interface.

---

10-19: Session parameter properly passed in all call sites

• In packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (lines 1506–1511), signInWithOAuth(this._interface, {…}, session) is invoked with the session obtained from _getSession().
• In the same file (lines 253–256), addNewOAuthProviderOrScope(this._interface, {…}, options.session) is invoked with options.session.

All internal callers now supply the new session parameter; no outstanding changes required.

apps/backend/src/lib/users.tsx (1)

6-31: Helper cleanly encapsulates anonymous upgrade vs. create

The branching on currentUser?.is_anonymous with explicit is_anonymous: false on upgrade is clear and keeps CRUD concerns centralized in handlers.

apps/backend/src/app/api/latest/auth/oauth/callback/[provider_id]/route.tsx (2)

356-399: Good: use createOrUpgradeAnonymousUser, then attach OAuth auth method

This replaces bespoke create logic and correctly anchors OAuth linkage to the (possibly upgraded) user. Token storage occurs after linkage.

---

280-354: Email merge strategy path creates both OAuth account and authMethod – verify flags

In the 'link_method' branch you create an OAuth account and a related OAuth auth method, but you don’t set allowConnectedAccounts/allowSignIn like in the signup path. If defaults aren’t permissive, linking may not allow sign-in.

Check defaults of projectUserOAuthAccount in Prisma schema/handlers. If needed, mirror the flags:

allowConnectedAccounts: true,
allowSignIn: true,

apps/backend/src/lib/tokens.tsx (2)

57-63: JWKS assembly for anonymous and non-anonymous audiences looks good

Including both audiences’ keys behind the allowAnonymous flag aligns with per-audience signing and the new kid separation. LGTM.

---

65-112: Confirm allowAnonymous flags on all decodeAccessToken call sites

I’ve located the four call sites where decodeAccessToken is invoked with an explicit allowAnonymous value. Please review each to ensure that anonymous tokens are being correctly permitted or rejected according to your business rules:

• apps/backend/src/route-handlers/smart-request.tsx
  • Line 184: decodeAccessToken(options.token, { allowAnonymous: true }) in extractUserIdAndRefreshTokenIdFromAccessToken
  • Line 205: decodeAccessToken(options.token, { allowAnonymous: false }) in extractUserFromAdminAccessToken

• apps/backend/src/oauth/model.tsx
  • Line 204: decodeAccessToken(accessToken, { allowAnonymous: true }) in getAccessToken

• apps/backend/src/app/api/latest/auth/oauth/authorize/[provider_id]/route.tsx
  • Line 81: decodeAccessToken(query.token, { allowAnonymous: true }) when handling an OAuth “link” flow

Verify that each of these uses aligns with when you intend to allow anonymous access versus requiring a fully authenticated token.

packages/stack-shared/src/interface/client-interface.ts (4)

855-868: Session-aware magic link sign-in: LGTM

Passing session through aligns with the broader session model. Call sites were updated accordingly.

---

883-899: Session-aware MFA sign-in: LGTM

Propagating session makes the flow consistent with other auth methods.

---

913-925: Session-aware passkey sign-in: LGTM

Signature and call propagation look correct.

---

948-949: OAuth URL now injects current access token: LGTM

Grabbing a likely-valid token and injecting it as token improves link/upgrade flows. Good guard with 20s minimum lifetime.

Also applies to: 976-980

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (3)

1505-1516: OAuth sign-in now passes session: LGTM

Good move to obtain and pass the current session to the helper; matches the updated interface.

---

1627-1633: Magic link sign-in passes session consistently: LGTM

Matches the new interface and surrounding patterns.

---

1808-1809: Passkey sign-in passes session to server call: LGTM

The flow looks correct and matches initiate → WebAuthn → server verify.

apps/backend/src/app/api/latest/users/crud.tsx (6)

5-17: Imports update looks good

Adding Tenancy and PrismaClient is appropriate for the new helpers; switching query schema types to yupString aligns with the "string booleans" convention used elsewhere.

---

416-419: List query schema changes are consistent

• desc: string oneOf ["true","false"]
• include_anonymous: string oneOf ["true","false"]

Matches how other endpoints model booleans as strings. No issues.

---

440-444: Default exclude-anonymous filter is correct

Where clause excludes anonymous users unless include_anonymous="true". This aligns with the PR objectives and prevents accidental exposure.

---

477-477: Order-by direction switch works with string booleans

Using query.desc === 'true' is consistent with the schema. No issues.

---

646-646: Create personal team call placement is fine, but depends on the 'creator_user_id' fix above

Once creator_user_id is set to user.id, the membership will exist and the selection update in createPersonalTeamIfEnabled will succeed. Without that change, this can fail at runtime.

Would you like me to add a small integration test to assert: (a) team is created, (b) membership exists, (c) isSelected is TRUE on signup?

---

1079-1091: Broadened allowedErrorTypes: confirm intent and impact

Switching allowedErrorTypes from [StatusError] to [Object] will allow any thrown value to be considered an "allowed" error by the route handler. This might inadvertently surface unexpected/internal errors to clients or alter status code mapping.

• If this is to accommodate KnownErrors that don’t extend StatusError, consider explicitly including those base classes/types instead of Object.
• Otherwise, ensure the route handler still normalizes unknown errors to safe 5xx responses.

Do you want me to adjust allowedErrorTypes to a narrower set (e.g., [StatusError, KnownErrors.BaseKnownError]) and update the handler typing accordingly?

apps/e2e/tests/backend/endpoints/api/v1/auth/anonymous/sign-up.test.ts (1)

45-50: Test intent now matches updated behavior (200 on anon sign-up for new projects).

Renamed description and assertions align with the PR objective of enabling anonymous sign-up on new projects. This resolves the earlier concern about contradictory wording vs. behavior.

packages/template/src/lib/stack-app/common.ts (1)

32-33: Don’t encode deprecation in the string literal; use JSDoc @deprecated instead

Embedding “[deprecated]” in the literal is a breaking API change for all existing consumers who pass "anonymous-if-exists". Keep the literal stable and mark it deprecated via JSDoc so type-checkers warn without breaking runtime behavior.

Apply locally:

-    or?: 'redirect' | 'throw' | 'return-null' | 'anonymous' | /** @deprecated */ 'anonymous-if-exists[deprecated]',
+    or?: 'redirect' | 'throw' | 'return-null' | 'anonymous' | /** @deprecated */ 'anonymous-if-exists',

Follow-up in dependent call sites (outside this file) to keep types consistent:

- props.app.getUser({ or: "anonymous-if-exists[deprecated]" })
+ props.app.getUser({ or: "anonymous-if-exists" })

- if (crud?.is_anonymous && options?.or !== "anonymous" && options?.or !== "anonymous-if-exists[deprecated]") {
+ if (crud?.is_anonymous && options?.or !== "anonymous" && options?.or !== "anonymous-if-exists") {

Script to find/verify all occurrences that need updating:

#!/bin/bash
# Find all uses of the deprecated-in-string variant
rg -nP --hidden --glob '!**/dist/**' "anonymous-if-exists\[deprecated\]" -C2

apps/e2e/tests/backend/endpoints/api/v1/auth/anonymous/anonymous-comprehensive.test.ts (3)

76-107: Clarify “rejected without header” vs header explicitly set to "false"

The helper unconditionally injects X-Stack-Allow-Anonymous-User: "true"; this test overrides it to "false". That’s functionally fine if the backend only accepts the literal "true", but the name/comments assert “without header,” which is misleading.

Option A (rename test to reflect behavior):

-it("anonymous users are rejected without X-Stack-Allow-Anonymous-User header", async ({ expect }) => {
+it('anonymous users are rejected when X-Stack-Allow-Anonymous-User is not "true"', async ({ expect }) => {
@@
-  // Try to access an endpoint without the header (niceBackendFetch adds it by default unless explicitly set to false)
+  // Try to access an endpoint with the header explicitly not set to "true"

Option B (preferred long-term): add a testing knob to niceBackendFetch (e.g., allowAnonymous: true | false | "omit") to truly omit the header when needed. I can draft that change if you want.

---

171-197: Snapshot contradicts test intent; assert presence of both anonymous and non-anonymous users

Comment says “Should include both users,” but the snapshot only asserts one non-anonymous user. Replace with explicit presence checks.

-  // Should include both users
-  expect(users).toMatchInlineSnapshot(`
-    [
-      {
-        "auth_with_email": true,
-        ...
-        "is_anonymous": false,
-        ...
-      },
-    ]
-  `);
+  // Should include both users
+  expect(Array.isArray(users)).toBe(true);
+  expect(users.length).toBeGreaterThanOrEqual(2);
+  expect(users.some((u: any) => u.is_anonymous === true)).toBe(true);
+  expect(users.some((u: any) => u.is_anonymous === false)).toBe(true);

---

50-74: Make JWKS assertions resilient to key rotation and multiple keys per audience

Hard-coding exact lengths and expecting 4 unique kids will flake when old and new keys coexist. Assert relative properties and superset relations instead.

   expect(regularJwks.status).toBe(200);
-  const regularKeys = regularJwks.body.keys;
-  expect(regularKeys).toHaveLength(2);
+  const regularKeys = regularJwks.body.keys;
+  expect(Array.isArray(regularKeys)).toBe(true);
+  expect(regularKeys.length).toBeGreaterThanOrEqual(1);

@@
   expect(anonymousJwks.status).toBe(200);
-  const allKeys = anonymousJwks.body.keys;
-  expect(allKeys).toHaveLength(4);
+  const allKeys = anonymousJwks.body.keys;
+  expect(Array.isArray(allKeys)).toBe(true);
+  expect(allKeys.length).toBeGreaterThan(regularKeys.length);

-  // Check that the kids are different
-  const kids = allKeys.map((key: any) => key.kid);
-  expect(new Set(kids).size).toBe(4);
+  // Check that include_anonymous adds at least one new kid
+  const regularKidSet = new Set(regularKeys.map((k: any) => k.kid));
+  const allKidSet = new Set(allKeys.map((k: any) => k.kid));
+  expect(regularKidSet.size).toBeGreaterThanOrEqual(1);
+  for (const kid of regularKidSet) expect(allKidSet.has(kid)).toBe(true);
+  expect(allKidSet.size).toBeGreaterThan(regularKidSet.size);