Turnstile integration for fraud protection

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "packages/private"]
+	path = packages/private
+	url = https://github.com/stack-auth/private.git
+	branch = main

apps/backend/.env

@@ -41,7 +41,7 @@ STACK_EMAIL_PORT=# for local inbucket: 8129
 STACK_EMAIL_USERNAME=# for local inbucket: test
 STACK_EMAIL_PASSWORD=# for local inbucket: none
 STACK_EMAIL_SENDER=# for local inbucket: noreply@test.com
-STACK_EMAILABLE_API_KEY=# for Emailable email validation, see https://emailable.com
+STACK_EMAILABLE_API_KEY=# Emailable API key for email validation, see https://emailable.com. Use a test key (starting with "test_") for local dev — it does not consume credits. Set to "disable_email_validation" to disable.
 
 STACK_DEFAULT_EMAIL_CAPACITY_PER_HOUR=# the number of emails a new project can send. Defaults to 200 
 

apps/backend/.env.development

@@ -17,6 +17,19 @@ STACK_SEED_INTERNAL_PROJECT_SECRET_SERVER_KEY=this-secret-server-key-is-for-loca
 STACK_SEED_INTERNAL_PROJECT_SUPER_SECRET_ADMIN_KEY=this-super-secret-admin-key-is-for-local-development-only
 
 STACK_OAUTH_MOCK_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}14
+STACK_TURNSTILE_SITEVERIFY_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}14/turnstile/siteverify
+
+# Cloudflare Turnstile test keys — always-pass widgets, no real challenges
+# See https://developers.cloudflare.com/turnstile/troubleshooting/testing/
+NEXT_PUBLIC_STACK_BOT_CHALLENGE_SITE_KEY=1x00000000000000000000AA
+NEXT_PUBLIC_STACK_BOT_CHALLENGE_INVISIBLE_SITE_KEY=1x00000000000000000000BB
+STACK_TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
+# Set to true to disable Turnstile entirely in local development.
+# This skips invisible/visible bot challenge flow and removes the Turnstile risk penalty.
+STACK_DISABLE_BOT_CHALLENGE=false
+# Default behavior is to block sign-up if the visible challenge cannot be completed.
+# Flip this only when you intentionally want local sign-up to continue during Turnstile outages.
+STACK_ALLOW_SIGN_UP_ON_VISIBLE_BOT_CHALLENGE_FAILURE=false
 
 STACK_GITHUB_CLIENT_ID=MOCK
 STACK_GITHUB_CLIENT_SECRET=MOCK
@@ -47,6 +60,10 @@ STACK_DEFAULT_EMAIL_CAPACITY_PER_HOUR=10000
 STACK_SVIX_SERVER_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}13
 STACK_SVIX_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2NTUxNDA2MzksImV4cCI6MTk3MDUwMDYzOSwibmJmIjoxNjU1MTQwNjM5LCJpc3MiOiJzdml4LXNlcnZlciIsInN1YiI6Im9yZ18yM3JiOFlkR3FNVDBxSXpwZ0d3ZFhmSGlyTXUifQ.En8w77ZJWbd0qrMlHHupHUB-4cx17RfzFykseg95SUk
 
+# Trusted reverse proxy for reading real client IP addresses.
+# Set to "vercel", "cloudflare", or leave empty/unset for no proxy trust.
+STACK_TRUSTED_PROXY=
+
 STACK_ARTIFICIAL_DEVELOPMENT_DELAY_MS=500
 
 STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING=yes
@@ -69,6 +86,8 @@ STACK_EMAIL_MONITOR_INBUCKET_API_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_P
 STACK_EMAIL_MONITOR_USE_INBUCKET=true
 STACK_EMAIL_MONITOR_SECRET_TOKEN=this-secret-token-is-for-local-development-only
 
+STACK_EMAILABLE_API_KEY=
+
 # S3 Configuration for local development using s3mock
 STACK_S3_ENDPOINT=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}21
 STACK_S3_REGION=us-east-1

apps/backend/package.json

@@ -91,6 +91,7 @@
     "chokidar-cli": "^3.0.0",
     "dotenv": "^16.4.5",
     "dotenv-cli": "^7.3.0",
+    "emailable": "^3.1.1",
     "freestyle-sandboxes": "^0.1.6",
     "jiti": "^2.6.1",
     "jose": "^6.1.3",

apps/backend/prisma/migrations/20260308000000_add_signup_fraud_protection/migration.sql

@@ -0,0 +1,19 @@
+ALTER TABLE "ProjectUser" ADD COLUMN "signUpRiskScoreBot" SMALLINT NOT NULL DEFAULT 0;
+ALTER TABLE "ProjectUser" ADD COLUMN "signUpRiskScoreFreeTrialAbuse" SMALLINT NOT NULL DEFAULT 0;
+
+ALTER TABLE "ProjectUser"
+  ADD CONSTRAINT "ProjectUser_risk_score_bot_range"
+  CHECK ("signUpRiskScoreBot" >= 0 AND "signUpRiskScoreBot" <= 100) NOT VALID;
+
+ALTER TABLE "ProjectUser"
+  ADD CONSTRAINT "ProjectUser_risk_score_free_trial_abuse_range"
+  CHECK ("signUpRiskScoreFreeTrialAbuse" >= 0 AND "signUpRiskScoreFreeTrialAbuse" <= 100) NOT VALID;
+
+ALTER TABLE "ProjectUser" ADD COLUMN "signUpCountryCode" TEXT;
+
+ALTER TABLE "ProjectUser"
+  ADD COLUMN "signedUpAt" TIMESTAMP(3),
+  ADD COLUMN "signUpIp" TEXT,
+  ADD COLUMN "signUpIpTrusted" BOOLEAN,
+  ADD COLUMN "signUpEmailNormalized" TEXT,
+  ADD COLUMN "signUpEmailBase" TEXT;

apps/backend/prisma/migrations/20260308000001_backfill_signup_fraud_protection/migration.sql

@@ -0,0 +1,16 @@
+-- SINGLE_STATEMENT_SENTINEL
+-- CONDITIONALLY_REPEAT_MIGRATION_SENTINEL
+WITH to_update AS (
+    SELECT "projectUserId", "tenancyId"
+    FROM "ProjectUser"
+    WHERE "signedUpAt" IS NULL
+    LIMIT 10000
+),
+updated AS (
+    UPDATE "ProjectUser" pu
+    SET "signedUpAt" = pu."createdAt"
+    FROM to_update tu
+    WHERE pu."tenancyId" = tu."tenancyId" AND pu."projectUserId" = tu."projectUserId"
+    RETURNING 1
+)
+SELECT COUNT(*) > 0 AS should_repeat_migration FROM updated;

apps/backend/prisma/migrations/20260308000001_backfill_signup_fraud_protection/tests/backfill-and-defaults.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 tenancyId = randomUUID();
+  const regularUserId = randomUUID();
+  const anonUserId = 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 (${regularUserId}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW())`;
+  await sql`INSERT INTO "ProjectUser" ("projectUserId", "tenancyId", "mirroredProjectId", "mirroredBranchId", "createdAt", "updatedAt", "lastActiveAt", "isAnonymous") VALUES (${anonUserId}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW(), true)`;
+
+  return { regularUserId, anonUserId };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  for (const userId of [ctx.regularUserId, ctx.anonUserId]) {
+    const rows = await sql`
+      SELECT "signedUpAt", "createdAt", "signUpRiskScoreBot", "signUpRiskScoreFreeTrialAbuse"
+      FROM "ProjectUser"
+      WHERE "projectUserId" = ${userId}::uuid
+    `;
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0].signedUpAt.toISOString()).toBe(rows[0].createdAt.toISOString());
+    expect(rows[0].signUpRiskScoreBot).toBe(0);
+    expect(rows[0].signUpRiskScoreFreeTrialAbuse).toBe(0);
+  }
+};

apps/backend/prisma/migrations/20260308000002_finalize_signup_fraud_protection/migration.sql

@@ -0,0 +1,65 @@
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+CREATE INDEX CONCURRENTLY IF NOT EXISTS "ProjectUser_signedUpAt_asc"
+  ON "ProjectUser"("tenancyId", "isAnonymous", "signedUpAt" ASC);
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+CREATE INDEX CONCURRENTLY IF NOT EXISTS "ProjectUser_signUpIp_recent_idx"
+  ON "ProjectUser"("tenancyId", "isAnonymous", "signUpIp", "signedUpAt");
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+CREATE INDEX CONCURRENTLY IF NOT EXISTS "ProjectUser_signUpEmailBase_recent_idx"
+  ON "ProjectUser"("tenancyId", "isAnonymous", "signUpEmailBase", "signedUpAt");
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+ALTER TABLE "ProjectUser" VALIDATE CONSTRAINT "ProjectUser_risk_score_bot_range";
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+ALTER TABLE "ProjectUser" VALIDATE CONSTRAINT "ProjectUser_risk_score_free_trial_abuse_range";
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+CREATE OR REPLACE FUNCTION "set_project_user_signed_up_at_from_created_at"()
+RETURNS TRIGGER AS $$
+BEGIN
+  IF NEW."signedUpAt" IS NULL THEN
+    NEW."signedUpAt" := NEW."createdAt";
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+CREATE TRIGGER "ProjectUser_set_signedUpAt_from_createdAt"
+BEFORE INSERT ON "ProjectUser"
+FOR EACH ROW
+EXECUTE FUNCTION "set_project_user_signed_up_at_from_created_at"();
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+ALTER TABLE "ProjectUser"
+  ADD CONSTRAINT "ProjectUser_signedUpAt_not_null"
+  CHECK ("signedUpAt" IS NOT NULL) NOT VALID;
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+ALTER TABLE "ProjectUser" VALIDATE CONSTRAINT "ProjectUser_signedUpAt_not_null";
+
+-- SPLIT_STATEMENT_SENTINEL
+-- SINGLE_STATEMENT_SENTINEL
+-- RUN_OUTSIDE_TRANSACTION_SENTINEL
+ALTER TABLE "ProjectUser" ALTER COLUMN "signedUpAt" SET NOT NULL;

apps/backend/prisma/migrations/20260308000002_finalize_signup_fraud_protection/tests/constraints-validated.ts

@@ -0,0 +1,39 @@
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const postMigration = async (sql: Sql) => {
+  const triggers = await sql`
+    SELECT tgname
+    FROM pg_trigger
+    WHERE tgrelid = '"ProjectUser"'::regclass
+      AND tgname = 'ProjectUser_set_signedUpAt_from_createdAt'
+      AND NOT tgisinternal
+  `;
+  expect(triggers).toHaveLength(1);
+
+  const constraints = await sql`
+    SELECT conname, convalidated
+    FROM pg_constraint
+    WHERE conrelid = '"ProjectUser"'::regclass
+      AND conname IN (
+        'ProjectUser_risk_score_bot_range',
+        'ProjectUser_risk_score_free_trial_abuse_range',
+        'ProjectUser_signedUpAt_not_null'
+      )
+    ORDER BY conname
+  `;
+
+  expect(constraints).toHaveLength(3);
+  for (const c of constraints) {
+    expect(c.convalidated, `${c.conname} should be validated`).toBe(true);
+  }
+
+  const colInfo = await sql`
+    SELECT is_nullable, column_default
+    FROM information_schema.columns
+    WHERE table_name = 'ProjectUser' AND column_name = 'signedUpAt'
+  `;
+  expect(colInfo).toHaveLength(1);
+  expect(colInfo[0].is_nullable).toBe('NO');
+  expect(colInfo[0].column_default).toBe(null);
+};

apps/backend/prisma/migrations/20260308000002_finalize_signup_fraud_protection/tests/default-on-insert.ts

@@ -0,0 +1,23 @@
+import { randomUUID } from 'crypto';
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const postMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  const tenancyId = randomUUID();
+  const userId = 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 (${userId}::uuid, ${tenancyId}::uuid, ${projectId}, 'main', NOW(), NOW(), NOW())`;
+
+  const rows = await sql`
+    SELECT "signedUpAt", "createdAt"
+    FROM "ProjectUser"
+    WHERE "projectUserId" = ${userId}::uuid
+  `;
+
+  expect(rows).toHaveLength(1);
+  expect(rows[0].signedUpAt).not.toBeNull();
+  expect(rows[0].signedUpAt.toISOString()).toBe(rows[0].createdAt.toISOString());
+};

apps/backend/prisma/migrations/20260308000002_finalize_signup_fraud_protection/tests/indexes-exist.ts

@@ -0,0 +1,29 @@
+import type { Sql } from 'postgres';
+import { expect } from 'vitest';
+
+export const postMigration = async (sql: Sql) => {
+  const indexes = await sql`
+    SELECT indexname, indexdef
+    FROM pg_indexes
+    WHERE schemaname = current_schema()
+      AND tablename = 'ProjectUser'
+      AND indexname IN (
+        'ProjectUser_signedUpAt_asc',
+        'ProjectUser_signUpIp_recent_idx',
+        'ProjectUser_signUpEmailBase_recent_idx'
+      )
+    ORDER BY indexname
+  `;
+
+  expect(indexes.map((row) => row.indexname)).toEqual([
+    'ProjectUser_signUpEmailBase_recent_idx',
+    'ProjectUser_signUpIp_recent_idx',
+    'ProjectUser_signedUpAt_asc',
+  ]);
+
+  const indexDefByName = Object.fromEntries(indexes.map((row) => [row.indexname, row.indexdef]));
+
+  expect(indexDefByName['ProjectUser_signedUpAt_asc']).toContain('"tenancyId", "isAnonymous", "signedUpAt"');
+  expect(indexDefByName['ProjectUser_signUpIp_recent_idx']).toContain('"tenancyId", "isAnonymous", "signUpIp", "signedUpAt"');
+  expect(indexDefByName['ProjectUser_signUpEmailBase_recent_idx']).toContain('"tenancyId", "isAnonymous", "signUpEmailBase", "signedUpAt"');
+};

apps/backend/prisma/schema.prisma

@@ -268,12 +268,24 @@ model ProjectUser {
   requiresTotpMfa        Boolean @default(false)
   totpSecret             Bytes?
   isAnonymous            Boolean @default(false)
+  signUpCountryCode      String?
 
   // Admin restriction fields - can be set by signup rules or manually by admins
   restrictedByAdmin               Boolean @default(false)
   restrictedByAdminReason         String? // Publicly viewable reason (shown to user)
   restrictedByAdminPrivateDetails String? // Private details (server access only)
 
+  // Sign-up metadata
+  signedUpAt                      DateTime
+  signUpIp                        String?
+  signUpIpTrusted                 Boolean?
+  signUpEmailNormalized           String?
+  signUpEmailBase                 String?
+
+  // Sign-up risk scores (0-100, set at sign-up time)
+  signUpRiskScoreBot              Int @default(0) @db.SmallInt
+  signUpRiskScoreFreeTrialAbuse   Int @default(0) @db.SmallInt
+
   projectUserOAuthAccounts ProjectUserOAuthAccount[]
   teamMembers              TeamMember[]
   contactChannels          ContactChannel[]
@@ -298,6 +310,9 @@ model ProjectUser {
   @@index([tenancyId, displayName(sort: Desc)], name: "ProjectUser_displayName_desc")
   @@index([tenancyId, createdAt(sort: Asc)], name: "ProjectUser_createdAt_asc")
   @@index([tenancyId, createdAt(sort: Desc)], name: "ProjectUser_createdAt_desc")
+  @@index([tenancyId, isAnonymous, signedUpAt(sort: Asc)], name: "ProjectUser_signedUpAt_asc")
+  @@index([tenancyId, isAnonymous, signUpIp, signedUpAt], name: "ProjectUser_signUpIp_recent_idx")
+  @@index([tenancyId, isAnonymous, signUpEmailBase, signedUpAt], name: "ProjectUser_signUpEmailBase_recent_idx")
   @@index([tenancyId, sequenceId], name: "ProjectUser_tenancyId_sequenceId_idx")
   @@index([shouldUpdateSequenceId, tenancyId], name: "ProjectUser_shouldUpdateSequenceId_idx")
 }

apps/backend/prisma/seed.ts

@@ -14,7 +14,7 @@ import {
 import { ensurePermissionDefinition, grantTeamPermission } from '@/lib/permissions';
 import { createOrUpdateProjectWithLegacyConfig, getProject } from '@/lib/projects';
 import { DEFAULT_BRANCH_ID, getSoleTenancyFromProjectBranch, type Tenancy } from '@/lib/tenancies';
-import { getPrismaClientForTenancy, globalPrismaClient, PrismaClientTransaction } from '@/prisma-client';
+import { PrismaClientTransaction, getPrismaClientForTenancy, globalPrismaClient } from '@/prisma-client';
 import { ALL_APPS } from '@stackframe/stack-shared/dist/apps/apps-config';
 import { DEFAULT_EMAIL_THEME_ID } from '@stackframe/stack-shared/dist/helpers/emails';
 import { AdminUserProjectsCrud, ProjectsCrud } from '@stackframe/stack-shared/dist/interface/crud/projects';
@@ -318,6 +318,9 @@ export async function seed() {
           tenancyId: internalTenancy.id,
           mirroredProjectId: 'internal',
           mirroredBranchId: DEFAULT_BRANCH_ID,
+          signedUpAt: new Date(),
+          signUpRiskScoreBot: 0,
+          signUpRiskScoreFreeTrialAbuse: 0,
         }
       });
 
@@ -447,6 +450,9 @@ export async function seed() {
           tenancyId: internalTenancy.id,
           mirroredProjectId: 'internal',
           mirroredBranchId: DEFAULT_BRANCH_ID,
+          signedUpAt: new Date(),
+          signUpRiskScoreBot: 0,
+          signUpRiskScoreFreeTrialAbuse: 0,
         }
       });