feat: add runtime signup approval setting

Adds a D1-backed runtime signup approval setting with REQUIRE_APPROVAL fallback, shared approval gate resolution, superadmin admin API endpoints, Admin Users UI control, docs, tests, staging validation, and CI evidence.

Author: simple-agent-manager[bot]

apps/api/src/auth.ts

@@ -10,6 +10,7 @@ import type { Env } from './env';
 import { createModuleLogger } from './lib/logger';
 import { readResponseJson } from './lib/runtime-validation';
 import { getBetterAuthSecret } from './lib/secrets';
+import { isSignupApprovalRequired } from './services/signup-approval';
 
 const log = createModuleLogger('auth');
 
@@ -320,7 +321,7 @@ export function createAuth(env: Env) {
       user: {
         create: {
           before: async (user) => {
-            if (env.REQUIRE_APPROVAL !== 'true') {
+            if (!(await isSignupApprovalRequired(env))) {
               // Open registration — defaults are fine (role='user', status='active')
               return { data: user };
             }

apps/api/src/db/migrations/0087_platform_settings.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS platform_settings (
+  key TEXT PRIMARY KEY NOT NULL,
+  value TEXT NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_by TEXT REFERENCES users(id) ON DELETE SET NULL
+);

apps/api/src/db/schema.ts

@@ -80,6 +80,18 @@ export const users = sqliteTable('users', {
     .default(sql`(cast(unixepoch() * 1000 as integer))`),
 });
 
+// =============================================================================
+// Platform Settings
+// =============================================================================
+export const platformSettings = sqliteTable('platform_settings', {
+  key: text('key').primaryKey(),
+  value: text('value').notNull(),
+  updatedAt: text('updated_at')
+    .notNull()
+    .default(sql`CURRENT_TIMESTAMP`),
+  updatedBy: text('updated_by').references(() => users.id, { onDelete: 'set null' }),
+});
+
 // =============================================================================
 // Sessions (BetterAuth)
 // =============================================================================

apps/api/src/middleware/auth.ts

@@ -5,7 +5,8 @@ import { createAuth } from '../auth';
 import type { Env } from '../env';
 import { log } from '../lib/logger';
 import { expectJsonRecord } from '../lib/runtime-validation';
-import { AppError, errors } from './error';
+import { assertUserAllowedBySignupApproval, isSignupApprovalRequired } from '../services/signup-approval';
+import { errors } from './error';
 
 /**
  * Extended context with authenticated user.
@@ -133,7 +134,7 @@ export function optionalAuth(): MiddlewareHandler<{ Bindings: Env }> {
  */
 export function requireApproved(): MiddlewareHandler<{ Bindings: Env }> {
   return async (c: Context<{ Bindings: Env }>, next: Next) => {
-    if (c.env.REQUIRE_APPROVAL !== 'true') {
+    if (!(await isSignupApprovalRequired(c.env))) {
       await next();
       return;
     }
@@ -154,12 +155,8 @@ export function requireApproved(): MiddlewareHandler<{ Bindings: Env }> {
       return;
     }
 
-    if (auth.user.status === 'suspended') {
-      throw errors.forbidden('Your account has been suspended');
-    }
-
-    // Default: pending
-    throw new AppError(403, 'APPROVAL_REQUIRED', 'Your account is pending admin approval');
+    assertUserAllowedBySignupApproval(true, auth.user);
+    await next();
   };
 }
 

apps/api/src/routes/admin.ts

@@ -9,15 +9,37 @@ import type { Env } from '../env';
 import { getUserId,requireApproved, requireAuth, requireSuperadmin } from '../middleware/auth';
 import { errors } from '../middleware/error';
 import { rateLimit } from '../middleware/rate-limit';
-import { AdminLogQuerySchema,AdminUserActionSchema, AdminUserRoleSchema, jsonValidator } from '../schemas';
+import { AdminLogQuerySchema,AdminUserActionSchema, AdminUserRoleSchema, jsonValidator, UpdateSignupApprovalConfigSchema } from '../schemas';
 import { getRuntimeLimits } from '../services/limits';
 import { CfApiError,getErrorTrends, getHealthSummary, getLogQueryRateLimit, queryCloudflareLogs, queryErrors } from '../services/observability';
+import { getSignupApprovalConfig, setSignupApprovalConfig } from '../services/signup-approval';
 
 const adminRoutes = new Hono<{ Bindings: Env }>();
 
 // All admin routes require auth + approval + superadmin
 adminRoutes.use('/*', requireAuth(), requireApproved(), requireSuperadmin());
 
+/**
+ * GET /api/admin/signup-approval - Read runtime signup approval config
+ */
+adminRoutes.get('/signup-approval', async (c) => {
+  const config = await getSignupApprovalConfig(c.env);
+  return c.json({ config });
+});
+
+/**
+ * PUT /api/admin/signup-approval - Update runtime signup approval config
+ * Body: { requireApproval: boolean }
+ */
+adminRoutes.put('/signup-approval', jsonValidator(UpdateSignupApprovalConfigSchema), async (c) => {
+  const body = c.req.valid('json');
+  const config = await setSignupApprovalConfig(c.env, {
+    requireApproval: body.requireApproval,
+    updatedBy: getUserId(c),
+  });
+  return c.json({ config });
+});
+
 /**
  * GET /api/admin/users - List all users
  * Optional query param: ?status=pending|active|suspended

apps/api/src/schemas/admin.ts

@@ -8,6 +8,10 @@ export const AdminUserRoleSchema = v.object({
   role: v.picklist(['admin', 'user']),
 });
 
+export const UpdateSignupApprovalConfigSchema = v.object({
+  requireApproval: v.boolean(),
+});
+
 export const AnalyticsForwardSchema = v.object({
   startDate: v.optional(v.string()),
   endDate: v.optional(v.string()),

apps/api/src/schemas/index.ts

@@ -97,6 +97,7 @@ export {
   AnalyticsForwardSchema,
   CreatePlatformCredentialSchema,
   UpdatePlatformCredentialSchema,
+  UpdateSignupApprovalConfigSchema,
 } from './admin';
 
 // Trigger schemas

apps/api/src/services/session-factory.ts

@@ -4,6 +4,7 @@ import { createAuth } from '../auth';
 import type { Env } from '../env';
 import { getBetterAuthSecret } from '../lib/secrets';
 import { errors } from '../middleware/error';
+import { assertSessionUserApproved } from './signup-approval';
 
 const DEFAULT_SESSION_DURATION_SECONDS = 7 * 24 * 60 * 60;
 
@@ -84,7 +85,7 @@ export async function buildSessionLoginResponse(
   env: Env,
   user: SessionFactoryUser,
 ): Promise<Response> {
-  assertUserCanCreateSession(env, user);
+  await assertUserCanCreateSession(env, user);
   const { cookieHeader, sessionCookie } = await createSessionCookieForUser(env, user.id);
   return new Response(
     JSON.stringify({
@@ -102,16 +103,6 @@ export async function buildSessionLoginResponse(
   );
 }
 
-export function assertUserCanCreateSession(env: Env, user: SessionFactoryUser): void {
-  if (env.REQUIRE_APPROVAL !== 'true') {
-    return;
-  }
-
-  const isAdmin = user.role === 'superadmin' || user.role === 'admin';
-  if (user.status === 'suspended') {
-    throw errors.forbidden('Your account has been suspended');
-  }
-  if (user.status !== 'active' && !isAdmin) {
-    throw errors.forbidden('Your account is pending admin approval');
-  }
+export async function assertUserCanCreateSession(env: Env, user: SessionFactoryUser): Promise<void> {
+  await assertSessionUserApproved(env, user);
 }

apps/api/src/services/signup-approval.ts

@@ -0,0 +1,129 @@
+import type { SignupApprovalConfig } from '@simple-agent-manager/shared';
+import { eq } from 'drizzle-orm';
+import { drizzle } from 'drizzle-orm/d1';
+
+import * as schema from '../db/schema';
+import type { Env } from '../env';
+import { createModuleLogger } from '../lib/logger';
+import { AppError, errors } from '../middleware/error';
+
+const log = createModuleLogger('signup-approval');
+
+export const SIGNUP_APPROVAL_SETTING_KEY = 'signup.requireApproval';
+
+function envRequiresApproval(env: Env): boolean {
+  return env.REQUIRE_APPROVAL === 'true';
+}
+
+function parseStoredBoolean(value: string | null | undefined): boolean | null {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return null;
+}
+
+function toIsoString(value: Date | string | null | undefined): string | null {
+  if (!value) return null;
+  if (value instanceof Date) return value.toISOString();
+  return value;
+}
+
+export async function getSignupApprovalConfig(env: Env): Promise<SignupApprovalConfig> {
+  const db = drizzle(env.DATABASE, { schema });
+  const row = await db
+    .select({
+      value: schema.platformSettings.value,
+      updatedAt: schema.platformSettings.updatedAt,
+      updatedBy: schema.platformSettings.updatedBy,
+    })
+    .from(schema.platformSettings)
+    .where(eq(schema.platformSettings.key, SIGNUP_APPROVAL_SETTING_KEY))
+    .get();
+
+  if (!row) {
+    return {
+      requireApproval: envRequiresApproval(env),
+      source: 'environment',
+      updatedAt: null,
+      updatedBy: null,
+    };
+  }
+
+  const parsed = parseStoredBoolean(row.value);
+  if (parsed === null) {
+    log.error('invalid_runtime_value', { key: SIGNUP_APPROVAL_SETTING_KEY });
+    return {
+      requireApproval: envRequiresApproval(env),
+      source: 'environment',
+      updatedAt: toIsoString(row.updatedAt),
+      updatedBy: row.updatedBy ?? null,
+    };
+  }
+
+  return {
+    requireApproval: parsed,
+    source: 'runtime',
+    updatedAt: toIsoString(row.updatedAt),
+    updatedBy: row.updatedBy ?? null,
+  };
+}
+
+export async function setSignupApprovalConfig(
+  env: Env,
+  input: { requireApproval: boolean; updatedBy: string },
+): Promise<SignupApprovalConfig> {
+  const db = drizzle(env.DATABASE, { schema });
+  const now = new Date().toISOString();
+
+  await db
+    .insert(schema.platformSettings)
+    .values({
+      key: SIGNUP_APPROVAL_SETTING_KEY,
+      value: input.requireApproval ? 'true' : 'false',
+      updatedAt: now,
+      updatedBy: input.updatedBy,
+    })
+    .onConflictDoUpdate({
+      target: schema.platformSettings.key,
+      set: {
+        value: input.requireApproval ? 'true' : 'false',
+        updatedAt: now,
+        updatedBy: input.updatedBy,
+      },
+    });
+
+  return {
+    requireApproval: input.requireApproval,
+    source: 'runtime',
+    updatedAt: now,
+    updatedBy: input.updatedBy,
+  };
+}
+
+export async function isSignupApprovalRequired(env: Env): Promise<boolean> {
+  const config = await getSignupApprovalConfig(env);
+  return config.requireApproval;
+}
+
+export async function assertSessionUserApproved(
+  env: Env,
+  user: { role?: string | null; status?: string | null },
+): Promise<void> {
+  assertUserAllowedBySignupApproval(await isSignupApprovalRequired(env), user);
+}
+
+export function assertUserAllowedBySignupApproval(
+  requireApproval: boolean,
+  user: { role?: string | null; status?: string | null },
+): void {
+  if (!requireApproval) {
+    return;
+  }
+
+  const isAdmin = user.role === 'superadmin' || user.role === 'admin';
+  if (user.status === 'suspended') {
+    throw errors.forbidden('Your account has been suspended');
+  }
+  if (user.status !== 'active' && !isAdmin) {
+    throw new AppError(403, 'APPROVAL_REQUIRED', 'Your account is pending admin approval');
+  }
+}

apps/api/tests/unit/auth.test.ts

@@ -60,15 +60,21 @@ function fakeEnv(requireApproval = 'true') {
 }
 
 function installExistingUsersQuery(existingUsers: Array<{ id: string }>) {
+  const get = vi.fn(async () => undefined);
   const all = vi.fn(async () => existingUsers);
   const limit = vi.fn(() => ({ all }));
   const where = vi.fn(() => ({ limit }));
   const from = vi.fn(() => ({ where }));
-  const select = vi.fn(() => ({ from }));
+  const select = vi.fn((fields?: Record<string, unknown>) => {
+    if (fields && 'value' in fields) {
+      return { from: vi.fn(() => ({ where: vi.fn(() => ({ get })) })) };
+    }
+    return { from };
+  });
 
   mocks.drizzle.mockReturnValue({ select });
 
-  return { all, from, limit, select, where };
+  return { all, from, get, limit, select, where };
 }
 
 async function getBeforeCreateHook(): Promise<BeforeCreateHook> {