feat: remove closed-beta approval gating, add username setup flow (#819)

- Auto-approve all non-revoked users on registration and migrate existing pending users
- Add blocking UsernameSetupModal for new users before cloud sync onboarding
- Strip pending-approval UI from admin, profile, and preferences sections
- Update REGISTRATION_MODE to 'open' in staging/prod configs
- Add username_set_at schema column and migration
- Add dev:check/dev:stop scripts and AGENTS.md rule for local server cleanup

Co-authored-by: wilhel1812 <wilhelm@linksim.link>

Author: wilhel1812

AGENTS.md

@@ -90,6 +90,7 @@
 - Local run reliability:
   - Restart local server whenever runtime/config/env changes can affect behavior.
   - Re-verify affected flows after restart before marking work as done.
+  - Do not leave local dev/watch servers running after a pass. Before handing back, run `npm run dev:check`; if it reports a LinkSim dev/watch server, run `npm run dev:stop` unless the user explicitly asked to keep it running.
 - Production preflight checklist (required before `deploy:prod:main`):
   - `npm run test`
   - `npm run build:bundle`

db/migrations/2026-05-03_open_registration_username_setup.sql

@@ -0,0 +1,19 @@
+PRAGMA foreign_keys = OFF;
+
+ALTER TABLE users ADD COLUMN username_set_at TEXT;
+
+UPDATE users
+SET username_set_at = COALESCE(updated_at, created_at)
+WHERE COALESCE(TRIM(username), '') != '';
+
+UPDATE users
+SET is_approved = 1,
+    approved_at = COALESCE(approved_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    approved_by_user_id = COALESCE(approved_by_user_id, 'system:open-registration'),
+    updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+WHERE is_admin = 0
+  AND is_moderator = 0
+  AND is_approved = 0
+  AND (approved_by_user_id IS NULL OR approved_by_user_id NOT LIKE 'revoked:%');
+
+PRAGMA foreign_keys = ON;

db/schema.sql

@@ -4,6 +4,7 @@ CREATE TABLE IF NOT EXISTS users (
   id TEXT PRIMARY KEY,
   username TEXT,
   email TEXT,
+  username_set_at TEXT,
   bio TEXT,
   access_request_note TEXT,
   idp_email TEXT,

docs/access-policy-templates.md

@@ -32,16 +32,16 @@ Use this profile when anonymous users must be able to open shared Simulation dee
 - Keep `/api/public-simulation` reachable without Access challenge.
 
 ### App authorization model
-- Keep `REGISTRATION_MODE=approval_required`.
+- Keep `REGISTRATION_MODE=open`.
 - Treat Access as identity proof for signed-in users.
 - Treat LinkSim visibility/role checks as the data authorization source.
 - Anonymous deep-link users must only load the shared/public Simulation bundle resolved by deep link.
 - Guest mode must not expose library browsing/discovery of unrelated objects.
 
-### LinkSim app-level approval
-- Keep `REGISTRATION_MODE=approval_required`.
+### LinkSim app-level authorization
+- Keep `REGISTRATION_MODE=open`.
 - Cloudflare Access answers “who can sign in”.
-- LinkSim approval answers “who can use simulation features”.
+- LinkSim visibility and role checks answer “who can use each simulation feature”.
 
 ## Hardened profile (optional)
 - Restrict to one IdP per environment.
@@ -51,15 +51,15 @@ Use this profile when anonymous users must be able to open shared Simulation dee
 ## Required env variables
 - `ACCESS_TEAM_DOMAIN`
 - `ACCESS_AUD`
-- `REGISTRATION_MODE=approval_required`
+- `REGISTRATION_MODE=open`
 - `ADMIN_USER_IDS=<comma-separated admin ids>`
 - `AUTH_OBSERVABILITY=true` (recommended)
 
 ## Validation checklist
 1. In baseline mode: unauthenticated user gets Access challenge.
 2. In guest deep-link mode: unauthenticated user can open a shared deep link without challenge.
 3. In guest deep-link mode: unauthenticated user cannot access authenticated APIs (`/api/me`, `/api/library`, admin routes).
-4. Authenticated non-approved user lands in pending flow.
+4. Authenticated new user must choose a username before cloud library/sync onboarding continues.
 5. Admin can open:
    - `/api/auth-diagnostics`
    - `/api/schema-diagnostics`
@@ -68,4 +68,4 @@ Use this profile when anonymous users must be able to open shared Simulation dee
 ## Common misconfigurations
 - Missing `ACCESS_AUD` or `ACCESS_TEAM_DOMAIN`.
 - `ALLOW_INSECURE_DEV_AUTH=true` in production.
-- Expecting Access policy alone to replace LinkSim role/approval controls.
+- Expecting Access policy alone to replace LinkSim resource role controls.

docs/cloudflare-auth-setup.md

@@ -44,17 +44,17 @@ Notes:
 - Native email+password user database is not provided by Cloudflare Access.
 - Passkeys are handled by your identity provider (GitHub), not by Access itself.
 
-## 4) Registration Mode (Invitation/Approval)
+## 4) Registration Mode
 
 Set in `wrangler.toml`:
 
-- `REGISTRATION_MODE = "approval_required"`
+- `REGISTRATION_MODE = "open"`
 - `ADMIN_USER_IDS = "<comma-separated user ids>"`
 
 In this mode:
 - First login creates a user profile
-- User remains blocked from library/sync APIs until approved by an admin
-- Admins approve/revoke from User Settings UI
+- Users choose a username before library/sync onboarding continues
+- Admin IDs bootstrap admin access for the listed identities
 
 ## 5) Configure Pages Environment Variables
 
@@ -63,7 +63,7 @@ In Pages project env vars (Production + Preview):
 - `ACCESS_TEAM_DOMAIN` = your team domain (without `https://`)
 - `ACCESS_AUD` = Access app AUD tag
 - `ADMIN_USER_IDS` = bootstrap admin user IDs
-- `REGISTRATION_MODE` = `approval_required`
+- `REGISTRATION_MODE` = `open`
 
 Do not enable local dev fallback vars in production.
 

functions/_lib/db.sharedSimulation.test.ts

@@ -8,6 +8,7 @@ const TABLE_COLUMNS: Record<string, string[]> = {
     "id",
     "username",
     "email",
+    "username_set_at",
     "bio",
     "access_request_note",
     "idp_email",

functions/_lib/db.ts

@@ -6,7 +6,7 @@ const DB_VISIBILITIES: DbVisibility[] = ["private", "public_read", "public_write
 const ROLES: ResourceRole[] = ["viewer", "editor", "admin"];
 
 let schemaReady: Promise<void> | null = null;
-const SCHEMA_VERSION = "2026-04-07a";
+const SCHEMA_VERSION = "2026-05-03a";
 type AccountState = "pending" | "approved" | "revoked";
 
 const dbVisibilityFromVisibility = (value: Visibility): DbVisibility => {
@@ -69,7 +69,7 @@ const slugifyName = (value: string): string =>
     .replace(/^-+|-+$/g, "")
     .replace(/-{2,}/g, "-");
 
-const DELIMITER_CHARS = /[+<>~\/]/g;
+const DELIMITER_CHARS = /[+<>~/]/g;
 const VARIATION_SELECTORS = /[\uFE0E\uFE0F]/g;
 
 export const canonicalizeSimulationLookupKey = (value: string): string =>
@@ -172,16 +172,6 @@ const sanitizeDefaultFrequencyPresetId = (value: unknown): string | null | undef
   return trimmed;
 };
 
-const deriveDefaultName = (userId: string, tokenPayload?: Record<string, unknown>): string => {
-  const fromName = sanitizeName(tokenPayload?.name);
-  if (fromName) return fromName;
-  const fromEmail = sanitizeEmail(tokenPayload?.email);
-  if (fromEmail) return fromEmail.split("@")[0];
-  const prefix = userId.includes("@") ? userId.split("@")[0] : userId;
-  const compact = prefix.replace(/[_-]+/g, " ").trim();
-  return sanitizeName(compact) ?? `User ${userId.slice(0, 6)}`;
-};
-
 const deriveDefaultEmail = (userId: string, tokenPayload?: Record<string, unknown>): string => {
   const fromEmail = sanitizeEmail(tokenPayload?.email);
   if (fromEmail) return fromEmail;
@@ -216,16 +206,12 @@ const parseAdminUserIds = (env: Env): Set<string> => {
   );
 };
 
-const registrationMode = (env: Env): "open" | "approval_required" => {
-  const value = (env.REGISTRATION_MODE ?? "approval_required").trim().toLowerCase();
-  return value === "open" ? "open" : "approval_required";
-};
-
 const REQUIRED_COLUMNS: Record<string, string[]> = {
   users: [
     "id",
     "username",
     "email",
+    "username_set_at",
     "bio",
     "access_request_note",
     "idp_email",
@@ -320,6 +306,7 @@ const ensureSchema = async (env: Env): Promise<void> => {
             id TEXT PRIMARY KEY,
             username TEXT,
             email TEXT,
+            username_set_at TEXT,
             bio TEXT,
             access_request_note TEXT,
             idp_email TEXT,
@@ -441,6 +428,32 @@ const ensureSchema = async (env: Env): Promise<void> => {
       if (!userColumns.has("default_frequency_preset_id")) {
         await env.DB.prepare("ALTER TABLE users ADD COLUMN default_frequency_preset_id TEXT").run();
       }
+      if (!userColumns.has("username_set_at")) {
+        await env.DB.prepare("ALTER TABLE users ADD COLUMN username_set_at TEXT").run();
+        await env.DB
+          .prepare(
+            `UPDATE users
+             SET username_set_at = COALESCE(updated_at, created_at)
+             WHERE COALESCE(TRIM(username), '') != ''`,
+          )
+          .run();
+      }
+
+      const now = new Date().toISOString();
+      await env.DB
+        .prepare(
+          `UPDATE users
+           SET is_approved = 1,
+               approved_at = COALESCE(approved_at, ?),
+               approved_by_user_id = COALESCE(approved_by_user_id, 'system:open-registration'),
+               updated_at = ?
+           WHERE is_admin = 0
+             AND is_moderator = 0
+             AND is_approved = 0
+             AND (approved_by_user_id IS NULL OR approved_by_user_id NOT LIKE 'revoked:%')`,
+        )
+        .bind(now, now)
+        .run();
 
       const diagnostics = await getSchemaDiagnostics(env);
       if (!diagnostics.ok) {
@@ -462,6 +475,7 @@ type UserRow = {
   id: string;
   username: string | null;
   email: string | null;
+  username_set_at: string | null;
   bio: string | null;
   access_request_note: string | null;
   idp_email: string | null;
@@ -513,7 +527,8 @@ export const chooseIdentityReconcileCandidate = (
 
 const toUserProfile = (row: UserRow) => ({
   id: row.id,
-  username: sanitizeName(row.username) ?? "User",
+  username: sanitizeName(row.username) ?? "",
+  needsUsername: !row.username_set_at,
   email: sanitizeEmail(row.email) ?? "unknown@users.linksim.local",
   bio: row.bio ?? "",
   accessRequestNote: row.access_request_note ?? "",
@@ -554,7 +569,7 @@ const readUserRow = async (env: Env, userId: string): Promise<UserRow | null> =>
   await ensureSchema(env);
   return env.DB
     .prepare(
-      "SELECT id, username, email, bio, access_request_note, idp_email, idp_email_verified, avatar_url, email_public, default_frequency_preset_id, avatar_object_key, avatar_thumb_key, avatar_hash, avatar_bytes, avatar_content_type, is_admin, is_moderator, is_approved, approved_at, approved_by_user_id, created_at, updated_at FROM users WHERE id = ?",
+      "SELECT id, username, email, username_set_at, bio, access_request_note, idp_email, idp_email_verified, avatar_url, email_public, default_frequency_preset_id, avatar_object_key, avatar_thumb_key, avatar_hash, avatar_bytes, avatar_content_type, is_admin, is_moderator, is_approved, approved_at, approved_by_user_id, created_at, updated_at FROM users WHERE id = ?",
     )
     .bind(userId)
     .first<UserRow>();
@@ -570,7 +585,7 @@ const reconcileUserIdentityByIdpEmail = async (
 
   const rows = await env.DB
     .prepare(
-      `SELECT id, username, email, bio, access_request_note, idp_email, idp_email_verified, avatar_url, email_public, default_frequency_preset_id, avatar_object_key, avatar_thumb_key, avatar_hash, avatar_bytes, avatar_content_type, is_admin, is_moderator, is_approved, approved_at, approved_by_user_id, created_at, updated_at,
+      `SELECT id, username, email, username_set_at, bio, access_request_note, idp_email, idp_email_verified, avatar_url, email_public, default_frequency_preset_id, avatar_object_key, avatar_thumb_key, avatar_hash, avatar_bytes, avatar_content_type, is_admin, is_moderator, is_approved, approved_at, approved_by_user_id, created_at, updated_at,
               CASE
                 WHEN lower(idp_email) = lower(?) AND idp_email_verified = 1 THEN 'verified_idp_email'
                 WHEN lower(email) = lower(?) THEN 'legacy_email'
@@ -684,61 +699,57 @@ export const ensureUser = async (
     await env.DB.prepare("DELETE FROM deleted_users WHERE id = ?").bind(userId).run();
   }
   const now = new Date().toISOString();
-  const username = deriveDefaultName(userId, tokenPayload);
   const email = deriveDefaultEmail(userId, tokenPayload);
   const idpEmail = deriveVerifiedIdpEmail(tokenPayload);
   const idpEmailVerified = idpEmail ? 1 : 0;
   const isBootstrapAdmin = parseAdminUserIds(env).has(userId.toLowerCase()) ? 1 : 0;
-  const autoApprove = isBootstrapAdmin === 1 || registrationMode(env) === "open";
+  const autoApprove = 1;
 
   await env.DB.prepare(
     `INSERT OR IGNORE INTO users
-      (id, username, email, bio, access_request_note, idp_email, idp_email_verified, avatar_url, email_public, avatar_object_key, avatar_thumb_key, avatar_hash, avatar_bytes, avatar_content_type, is_admin, is_moderator, is_approved, approved_at, approved_by_user_id, created_at, updated_at)
-     VALUES (?, ?, ?, '', '', ?, ?, '', 1, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)`,
+      (id, username, email, username_set_at, bio, access_request_note, idp_email, idp_email_verified, avatar_url, email_public, avatar_object_key, avatar_thumb_key, avatar_hash, avatar_bytes, avatar_content_type, is_admin, is_moderator, is_approved, approved_at, approved_by_user_id, created_at, updated_at)
+     VALUES (?, '', ?, NULL, '', '', ?, ?, '', 1, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)`,
   )
     .bind(
       userId,
-      username,
       email,
       idpEmail || null,
       idpEmailVerified,
       isBootstrapAdmin,
       0,
-      autoApprove ? 1 : 0,
-      autoApprove ? now : null,
-      autoApprove ? userId : null,
+      autoApprove,
+      now,
+      "system:open-registration",
       now,
       now,
     )
     .run();
 
   await env.DB.prepare(
     `UPDATE users
-     SET username = COALESCE(NULLIF(TRIM(username), ''), ?),
-         email = COALESCE(NULLIF(TRIM(email), ''), ?),
+     SET email = COALESCE(NULLIF(TRIM(email), ''), ?),
          idp_email = CASE WHEN ? = 1 THEN COALESCE(NULLIF(TRIM(idp_email), ''), ?) ELSE idp_email END,
          idp_email_verified = CASE WHEN ? = 1 THEN 1 ELSE idp_email_verified END,
          is_admin = CASE WHEN ? = 1 THEN 1 ELSE is_admin END,
          is_moderator = CASE WHEN ? = 1 THEN 1 ELSE is_moderator END,
-         is_approved = CASE WHEN ? = 1 THEN 1 ELSE is_approved END,
+         is_approved = CASE WHEN ? = 1 AND (approved_by_user_id IS NULL OR approved_by_user_id NOT LIKE 'revoked:%') THEN 1 ELSE is_approved END,
          approved_at = CASE WHEN ? = 1 AND approved_at IS NULL THEN ? ELSE approved_at END,
          approved_by_user_id = CASE WHEN ? = 1 AND approved_by_user_id IS NULL THEN ? ELSE approved_by_user_id END,
          updated_at = ?
      WHERE id = ?`,
   )
     .bind(
-      username,
       email,
       idpEmailVerified,
       idpEmail || null,
       idpEmailVerified,
       isBootstrapAdmin,
       0,
-      autoApprove ? 1 : 0,
-      autoApprove ? 1 : 0,
+      autoApprove,
+      autoApprove,
       now,
-      autoApprove ? 1 : 0,
-      userId,
+      autoApprove,
+      "system:open-registration",
       now,
       userId,
     )
@@ -812,6 +823,7 @@ export const updateUserProfile = async (
   await env.DB.prepare(
     `UPDATE users
      SET username = ?,
+         username_set_at = CASE WHEN ? = 1 THEN COALESCE(username_set_at, ?) ELSE username_set_at END,
          email = ?,
          bio = ?,
          access_request_note = ?,
@@ -828,6 +840,8 @@ export const updateUserProfile = async (
   )
     .bind(
       nextName,
+      patch.username === undefined ? 0 : 1,
+      new Date().toISOString(),
       nextEmail,
       nextBio,
       nextAccessRequestNote,
@@ -910,7 +924,7 @@ export const listUsers = async (env: Env) => {
   await ensureSchema(env);
   const rows = await env.DB
     .prepare(
-      "SELECT id, username, email, bio, access_request_note, idp_email, idp_email_verified, avatar_url, email_public, default_frequency_preset_id, avatar_object_key, avatar_thumb_key, avatar_hash, avatar_bytes, avatar_content_type, is_admin, is_moderator, is_approved, approved_at, approved_by_user_id, created_at, updated_at FROM users ORDER BY created_at DESC LIMIT 2000",
+      "SELECT id, username, email, username_set_at, bio, access_request_note, idp_email, idp_email_verified, avatar_url, email_public, default_frequency_preset_id, avatar_object_key, avatar_thumb_key, avatar_hash, avatar_bytes, avatar_content_type, is_admin, is_moderator, is_approved, approved_at, approved_by_user_id, created_at, updated_at FROM users ORDER BY created_at DESC LIMIT 2000",
     )
     .all<UserRow>();
   return rows.results.map(toUserProfile);

functions/api/me.test.ts

@@ -34,6 +34,15 @@ describe("api/me", () => {
     expect(res.headers.get("cache-control")).toBe("no-store");
   });
 
+  it("returns username setup state on GET", async () => {
+    fetchUserProfileMock.mockResolvedValueOnce({ id: "u1", username: "", needsUsername: true });
+
+    const res = await onRequestGet(mkCtx(new Request("https://example.test/api/me")));
+
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.toEqual({ user: { id: "u1", username: "", needsUsername: true } });
+  });
+
   it("returns a controlled service unavailable response when auth verification times out", async () => {
     verifyAuthMock.mockRejectedValue(new Error("Auth verification timed out"));
     const res = await onRequestGet(mkCtx(new Request("https://example.test/api/me")));
@@ -66,4 +75,19 @@ describe("api/me", () => {
       expect.objectContaining({ defaultFrequencyPresetId: "mt-us" }),
     );
   });
+
+  it("passes username through PATCH for first username setup", async () => {
+    const req = new Request("https://example.test/api/me", {
+      method: "PATCH",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ username: "Ranger" }),
+    });
+    const res = await onRequestPatch(mkCtx(req));
+    expect(res.status).toBe(200);
+    expect(updateUserProfileMock).toHaveBeenCalledWith(
+      env,
+      "u1",
+      expect.objectContaining({ username: "Ranger" }),
+    );
+  });
 });