Merge branch 'analytics-event-tracking' of https://github.com/stack-auth/stack-auth into analytics-event-tracking

Author: BilalG1

AGENTS.md

@@ -23,7 +23,7 @@ You should ALWAYS add new E2E tests when you change the API or SDK interface. Ge
 - **Run some tests**: `pnpm test run <file-filters>`
 
 ### Database Commands
-- **Generate migration**: `pnpm db:migration-gen`
+- **Generate migration**: `pnpm db:migration-gen` — NOTE: don't forget to create tests for the migrations!
 - **Reset database** (rarely used): `pnpm db:reset`
 - **Seed database** (rarely used): `pnpm db:seed`
 - **Initialize database** (rarely used): `pnpm db:init`
@@ -100,8 +100,10 @@ To see all development ports, refer to the index.html of `apps/dev-launchpad/pub
 - NEVER implement a hacky solution without EXPLICIT approval from the user. Always go the extra mile to make sure the solution is clean, maintainable, and robust.
 - Fail early, fail loud. Fail fast with an error instead of silently continuing.
 - Do NOT use `as`/`any`/type casts or anything else like that to bypass the type system unless you specifically asked the user about it. Most of the time a place where you would use type casts is not one where you actually need them. Avoid wherever possible.
-- When writing database migration files, assume that we have >1,000,000 rows in every table (unless otherwise specified). This means you may have to use CONDITIONALLY_REPEAT_MIGRATION_SENTINEL to avoid running the migration and things like concurrent index builds; see the existing migrations for examples.
+- When writing database migration files, assume that we have >1,000,000 rows in every table (unless otherwise specified). This means you may have to use CONDITIONALLY_REPEAT_MIGRATION_SENTINEL to avoid running the migration and things like concurrent index builds; see the existing migrations for examples. One common pattern is to add a temporary extra boolean column
 - Each migration file runs in its own transaction with a relatively short timeout. Split long-running operations into separate migration files to avoid timeouts. For example, when adding CHECK constraints, use `NOT VALID` in one migration, then `VALIDATE CONSTRAINT` in a separate migration file.
+- Note that each database migration file is executed in a single transaction. Even with the run-outside-transaction sentinel, the transaction will still continue during the entire migration file. If you want to split things up into multiple transactions, put it into their own migration files.
+- When writing database migration files, ALWAYS ALWAYS add tests for all the potential edge cases! See the folder structure of the other migrations to see how that works.
 - **When building frontend code, always carefully deal with loading and error states.** Be very explicit with these; some components make this easy, eg. the button onClick already takes an async callback for loading state, but make sure this is done everywhere, and make sure errors are NEVER just silently swallowed.
 - Any design components you add or modify in the dashboard, update the Playground page accordingly to showcase the changes.
 - Unless very clearly equivalent from types, prefer explicit null/undefinedness checks over boolean checks, eg. `foo == null` instead of `!foo`.

apps/backend/prisma/migrations/20260201400000_add_restricted_by_admin_fields/tests/default-values.ts

@@ -0,0 +1,31 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  const tenancyId = randomUUID();
+  const userId1 = randomUUID();
+  const userId2 = randomUUID();
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId}, NOW(), NOW(), 'Test', '', false)`;
+  await sql`INSERT INTO "Tenancy" ("id", "createdAt", "updatedAt", "projectId", "branchId", "hasNoOrganization") VALUES (${tenancyId}::uuid, NOW(), NOW(), ${projectId}, 'main', 'TRUE'::"BooleanTrue")`;
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt") VALUES (${userId1}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW())`;
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt") VALUES (${userId2}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW())`;
+
+  return { projectId };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  const rows = await sql`
+    SELECT "restrictedByAdmin", "restrictedByAdminReason"
+    FROM "ProjectUser"
+    WHERE "mirroredProjectId" = ${ctx.projectId}
+  `;
+
+  expect(rows).toHaveLength(2);
+  for (const row of rows) {
+    expect(row.restrictedByAdmin).toBe(false);
+    expect(row.restrictedByAdminReason).toBeNull();
+  }
+};

apps/backend/prisma/migrations/20260201400001_add_restricted_by_admin_constraint/tests/constraint-enforcement.ts

@@ -0,0 +1,60 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  const tenancyId = randomUUID();
+  const unrestricted = randomUUID();
+  const restrictedWithReason = randomUUID();
+  const restrictedNoReason = randomUUID();
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId}, NOW(), NOW(), 'Test', '', false)`;
+  await sql`INSERT INTO "Tenancy" ("id", "createdAt", "updatedAt", "projectId", "branchId", "hasNoOrganization") VALUES (${tenancyId}::uuid, NOW(), NOW(), ${projectId}, 'main', 'TRUE'::"BooleanTrue")`;
+
+  // Unrestricted user (valid: false + null reason)
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt") VALUES (${unrestricted}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW())`;
+
+  // Restricted with reason
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt", "restrictedByAdmin", "restrictedByAdminReason") VALUES (${restrictedWithReason}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW(), true, 'spam')`;
+
+  // Restricted without reason
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt", "restrictedByAdmin") VALUES (${restrictedNoReason}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW(), true)`;
+
+  return { projectId, tenancyId, unrestricted, restrictedWithReason, restrictedNoReason };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  // Existing valid rows should still be there
+  const rows = await sql`
+    SELECT "projectUserId", "restrictedByAdmin", "restrictedByAdminReason", "restrictedByAdminPrivateDetails"
+    FROM "ProjectUser"
+    WHERE "mirroredProjectId" = ${ctx.projectId}
+    ORDER BY "projectUserId"
+  `;
+  expect(rows).toHaveLength(3);
+
+  for (const row of rows) {
+    expect(row.restrictedByAdminPrivateDetails).toBeNull();
+  }
+
+  // Restricted user can have private details set
+  await sql`UPDATE "ProjectUser" SET "restrictedByAdminPrivateDetails" = 'internal notes' WHERE "projectUserId" = ${ctx.restrictedWithReason}::uuid`;
+
+  // INVALID: unrestricted user with a reason should fail
+  await expect(sql`
+    UPDATE "ProjectUser" SET "restrictedByAdminReason" = 'should fail' WHERE "projectUserId" = ${ctx.unrestricted}::uuid
+  `).rejects.toThrow(/ProjectUser_restricted_by_admin_consistency/);
+
+  // INVALID: unrestricted user with private details should fail
+  await expect(sql`
+    UPDATE "ProjectUser" SET "restrictedByAdminPrivateDetails" = 'should fail' WHERE "projectUserId" = ${ctx.unrestricted}::uuid
+  `).rejects.toThrow(/ProjectUser_restricted_by_admin_consistency/);
+
+  // VALID: new restricted user with all fields
+  const newUser = randomUUID();
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt", "restrictedByAdmin", "restrictedByAdminReason", "restrictedByAdminPrivateDetails") VALUES (${newUser}::uuid, ${ctx.tenancyId}::uuid, ${ctx.projectId}, 'main', NOW(), NOW(), NOW(), true, 'test', 'details')`;
+
+  // VALID: un-restricting clears reason and details
+  await sql`UPDATE "ProjectUser" SET "restrictedByAdmin" = false, "restrictedByAdminReason" = NULL, "restrictedByAdminPrivateDetails" = NULL WHERE "projectUserId" = ${newUser}::uuid`;
+};

apps/backend/prisma/migrations/20260213000000_outgoing_request_partial_dedup_index/tests/partial-unique-enforcement.ts

@@ -0,0 +1,38 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const dedupKey = `dedup-${randomUUID()}`;
+  const fulfilledKey = `fulfilled-${randomUUID()}`;
+
+  // Pending request
+  await sql`INSERT INTO "OutgoingRequest" ("id", "deduplicationKey", "qstashOptions") VALUES (${randomUUID()}::uuid, ${dedupKey}, '{"url":"http://test"}'::jsonb)`;
+
+  // Fulfilled request with a different key
+  await sql`INSERT INTO "OutgoingRequest" ("id", "deduplicationKey", "qstashOptions", "startedFulfillingAt") VALUES (${randomUUID()}::uuid, ${fulfilledKey}, '{"url":"http://test"}'::jsonb, NOW())`;
+
+  return { dedupKey, fulfilledKey };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  // Duplicate pending requests should still be rejected
+  await expect(sql`
+    INSERT INTO "OutgoingRequest" ("id", "deduplicationKey", "qstashOptions") VALUES (${randomUUID()}::uuid, ${ctx.dedupKey}, '{"url":"http://test2"}'::jsonb)
+  `).rejects.toThrow(/OutgoingRequest_deduplicationKey_pending_key/);
+
+  // Fulfill the original pending request
+  await sql`UPDATE "OutgoingRequest" SET "startedFulfillingAt" = NOW() WHERE "deduplicationKey" = ${ctx.dedupKey}`;
+
+  // Now we CAN insert a new pending request with the same dedup key
+  await sql`INSERT INTO "OutgoingRequest" ("id", "deduplicationKey", "qstashOptions") VALUES (${randomUUID()}::uuid, ${ctx.dedupKey}, '{"url":"http://test3"}'::jsonb)`;
+
+  // Fulfilled requests can share dedup keys freely
+  await sql`INSERT INTO "OutgoingRequest" ("id", "deduplicationKey", "qstashOptions", "startedFulfillingAt") VALUES (${randomUUID()}::uuid, ${ctx.fulfilledKey}, '{"url":"http://test4"}'::jsonb, NOW())`;
+
+  const pending = await sql`SELECT COUNT(*) as count FROM "OutgoingRequest" WHERE "deduplicationKey" = ${ctx.dedupKey} AND "startedFulfillingAt" IS NULL`;
+  expect(Number(pending[0].count)).toBe(1);
+
+  const fulfilled = await sql`SELECT COUNT(*) as count FROM "OutgoingRequest" WHERE "deduplicationKey" = ${ctx.dedupKey} AND "startedFulfillingAt" IS NOT NULL`;
+  expect(Number(fulfilled[0].count)).toBe(1);
+};

apps/backend/prisma/migrations/20260214000000_fix_trusted_domains_config/tests/already-correct.ts

@@ -0,0 +1,30 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  const domainId = randomUUID();
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId}, NOW(), NOW(), 'Test', '', false)`;
+
+  // Config that already has both parent AND child keys (correct format)
+  const config = {
+    [`domains.trustedDomains.${domainId}`]: {},
+    [`domains.trustedDomains.${domainId}.baseUrl`]: 'https://correct.com',
+    [`domains.trustedDomains.${domainId}.handlerPath`]: '/api',
+    'some.other.key': 'untouched',
+  };
+  await sql`INSERT INTO "EnvironmentConfigOverride" ("projectId", "branchId", "createdAt", "updatedAt", "config") VALUES (${projectId}, 'main', NOW(), NOW(), ${sql.json(config)})`;
+
+  return { projectId, domainId };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  const [row] = await sql`SELECT "config" FROM "EnvironmentConfigOverride" WHERE "projectId" = ${ctx.projectId}`;
+
+  expect(row.config[`domains.trustedDomains.${ctx.domainId}`]).toEqual({});
+  expect(row.config[`domains.trustedDomains.${ctx.domainId}.baseUrl`]).toBe('https://correct.com');
+  expect(row.config[`domains.trustedDomains.${ctx.domainId}.handlerPath`]).toBe('/api');
+  expect(row.config['some.other.key']).toBe('untouched');
+};

apps/backend/prisma/migrations/20260214000000_fix_trusted_domains_config/tests/fix-missing-parent-keys.ts

@@ -0,0 +1,32 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  const domainId = randomUUID();
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId}, NOW(), NOW(), 'Test', '', false)`;
+
+  // Config with child keys but MISSING parent key
+  const config = {
+    [`domains.trustedDomains.${domainId}.baseUrl`]: 'https://example.com',
+    [`domains.trustedDomains.${domainId}.handlerPath`]: '/handler',
+  };
+  await sql`INSERT INTO "EnvironmentConfigOverride" ("projectId", "branchId", "createdAt", "updatedAt", "config") VALUES (${projectId}, 'main', NOW(), NOW(), ${sql.json(config)})`;
+
+  return { projectId, domainId };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  const [row] = await sql`SELECT "config" FROM "EnvironmentConfigOverride" WHERE "projectId" = ${ctx.projectId}`;
+  const parentKey = `domains.trustedDomains.${ctx.domainId}`;
+
+  // Parent key should now exist as an empty object
+  expect(row.config).toHaveProperty(parentKey);
+  expect(row.config[parentKey]).toEqual({});
+
+  // Child keys should still be present and unchanged
+  expect(row.config[`${parentKey}.baseUrl`]).toBe('https://example.com');
+  expect(row.config[`${parentKey}.handlerPath`]).toBe('/handler');
+};

apps/backend/prisma/migrations/20260214000000_fix_trusted_domains_config/tests/mixed-entries.ts

@@ -0,0 +1,40 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId1 = `test-${randomUUID()}`;
+  const projectId2 = `test-${randomUUID()}`;
+  const domainOk = randomUUID();
+  const domainBroken = randomUUID();
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId1}, NOW(), NOW(), 'Test1', '', false)`;
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId2}, NOW(), NOW(), 'Test2', '', false)`;
+
+  // Project 1: correctly formatted (parent key present)
+  const config1 = {
+    [`domains.trustedDomains.${domainOk}`]: {},
+    [`domains.trustedDomains.${domainOk}.baseUrl`]: 'https://ok.com',
+  };
+  await sql`INSERT INTO "EnvironmentConfigOverride" ("projectId", "branchId", "createdAt", "updatedAt", "config") VALUES (${projectId1}, 'main', NOW(), NOW(), ${sql.json(config1)})`;
+
+  // Project 2: broken (parent key missing)
+  const config2 = {
+    [`domains.trustedDomains.${domainBroken}.baseUrl`]: 'https://broken.com',
+  };
+  await sql`INSERT INTO "EnvironmentConfigOverride" ("projectId", "branchId", "createdAt", "updatedAt", "config") VALUES (${projectId2}, 'main', NOW(), NOW(), ${sql.json(config2)})`;
+
+  return { projectId1, projectId2, domainOk, domainBroken };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  // Project 1: unchanged
+  const [row1] = await sql`SELECT "config" FROM "EnvironmentConfigOverride" WHERE "projectId" = ${ctx.projectId1}`;
+  expect(row1.config[`domains.trustedDomains.${ctx.domainOk}`]).toEqual({});
+  expect(row1.config[`domains.trustedDomains.${ctx.domainOk}.baseUrl`]).toBe('https://ok.com');
+
+  // Project 2: parent key added
+  const [row2] = await sql`SELECT "config" FROM "EnvironmentConfigOverride" WHERE "projectId" = ${ctx.projectId2}`;
+  expect(row2.config[`domains.trustedDomains.${ctx.domainBroken}`]).toEqual({});
+  expect(row2.config[`domains.trustedDomains.${ctx.domainBroken}.baseUrl`]).toBe('https://broken.com');
+};

apps/backend/prisma/migrations/20260214000000_fix_trusted_domains_config/tests/multiple-children.ts

@@ -0,0 +1,38 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  const domainId1 = randomUUID();
+  const domainId2 = randomUUID();
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId}, NOW(), NOW(), 'Test', '', false)`;
+
+  // Two different domains, both missing parent keys
+  const config = {
+    [`domains.trustedDomains.${domainId1}.baseUrl`]: 'https://one.com',
+    [`domains.trustedDomains.${domainId1}.handlerPath`]: '/one',
+    [`domains.trustedDomains.${domainId2}.baseUrl`]: 'https://two.com',
+    [`domains.trustedDomains.${domainId2}.handlerPath`]: '/two',
+    [`domains.trustedDomains.${domainId2}.extra`]: 'data',
+  };
+  await sql`INSERT INTO "EnvironmentConfigOverride" ("projectId", "branchId", "createdAt", "updatedAt", "config") VALUES (${projectId}, 'main', NOW(), NOW(), ${sql.json(config)})`;
+
+  return { projectId, domainId1, domainId2 };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  const [row] = await sql`SELECT "config" FROM "EnvironmentConfigOverride" WHERE "projectId" = ${ctx.projectId}`;
+
+  // Both parent keys should be added
+  expect(row.config[`domains.trustedDomains.${ctx.domainId1}`]).toEqual({});
+  expect(row.config[`domains.trustedDomains.${ctx.domainId2}`]).toEqual({});
+
+  // All child keys preserved
+  expect(row.config[`domains.trustedDomains.${ctx.domainId1}.baseUrl`]).toBe('https://one.com');
+  expect(row.config[`domains.trustedDomains.${ctx.domainId1}.handlerPath`]).toBe('/one');
+  expect(row.config[`domains.trustedDomains.${ctx.domainId2}.baseUrl`]).toBe('https://two.com');
+  expect(row.config[`domains.trustedDomains.${ctx.domainId2}.handlerPath`]).toBe('/two');
+  expect(row.config[`domains.trustedDomains.${ctx.domainId2}.extra`]).toBe('data');
+};

apps/backend/prisma/migrations/20260214000000_fix_trusted_domains_config/tests/no-trusted-domains.ts

@@ -0,0 +1,19 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+
+  await sql`INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode") VALUES (${projectId}, NOW(), NOW(), 'Test', '', false)`;
+
+  const config = { 'auth.allowSignUp': true, 'payments.testMode': true, 'some.nested.value': 42 };
+  await sql`INSERT INTO "EnvironmentConfigOverride" ("projectId", "branchId", "createdAt", "updatedAt", "config") VALUES (${projectId}, 'main', NOW(), NOW(), ${sql.json(config)})`;
+
+  return { projectId, originalConfig: config };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  const [row] = await sql`SELECT "config" FROM "EnvironmentConfigOverride" WHERE "projectId" = ${ctx.projectId}`;
+  expect(row.config).toEqual(ctx.originalConfig);
+};

apps/backend/prisma/migrations/20260214000000_fix_trusted_domains_config/tests/temp-cleanup.ts

@@ -0,0 +1,21 @@
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+// No preMigration needed - we just verify cleanup after the migration runs
+
+export const postMigration = async (sql: Sql) => {
+  // Temporary column should NOT exist after migration
+  const columns = await sql`
+    SELECT column_name FROM information_schema.columns
+    WHERE table_name = 'EnvironmentConfigOverride'
+    AND column_name = 'temp_trusted_domains_checked'
+  `;
+  expect(columns).toHaveLength(0);
+
+  // Temporary index should NOT exist after migration
+  const indices = await sql`
+    SELECT indexname FROM pg_indexes
+    WHERE indexname = 'temp_eco_trusted_domains_checked_idx'
+  `;
+  expect(indices).toHaveLength(0);
+};