@ramonclaudio/create-vexpo 0.1.0 → 0.1.2

package/dist/templates/default/__tests__/convex/pushTokens-upsert.test.ts

@@ -0,0 +1,146 @@
+/// <reference types="vite/client" />
+/**
+ * REAL convexTest coverage for pushTokens.upsert (authMutation).
+ *
+ * upsert insert-or-updates a single Expo push token row for the current user.
+ * It rate-limits on "userAction" (so the rateLimiter component must be
+ * registered) and reads existing rows by the "by_token" index, so the same
+ * token never duplicates: same owner -> patch + un-revoke; different owner ->
+ * reassign to the caller.
+ *
+ * Auth is driven exactly like _auth-harness.test.ts: seed a Better Auth
+ * user + session in the component db (capturing their REAL component ids),
+ * seed the mirrored app `users` row keyed by authId, then call with an
+ * identity whose subject == better-auth user id and sessionId == session id.
+ */
+import { ConvexError } from "convex/values";
+import { describe, expect, test } from "vitest";
+
+import { api } from "@/convex/_generated/api";
+
+import { identityFor, initConvexTest, seedAuthedUser } from "./_harness";
+
+describe("pushTokens.upsert", () => {
+  test("inserts a new token row owned by the authenticated user", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId } = await seedAuthedUser(t);
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+
+    const before = Date.now();
+    const tokenId = await asUser.mutation(api.pushTokens.upsert, {
+      token: "ExponentPushToken[aaa]",
+      deviceType: "ios",
+    });
+    const after = Date.now();
+
+    // Real DB effect: exactly one row, keyed to the app user, with the values
+    // the handler wrote.
+    const rows = await t.run(async (ctx) => ctx.db.query("pushTokens").collect());
+    expect(rows).toHaveLength(1);
+    const row = rows[0];
+    expect(row._id).toBe(tokenId);
+    expect(row.userId).toBe(appUserId);
+    expect(row.token).toBe("ExponentPushToken[aaa]");
+    expect(row.deviceType).toBe("ios");
+    // Insert path sets createdAt == updatedAt == lastSeenAt to "now".
+    expect(row.createdAt).toBeGreaterThanOrEqual(before);
+    expect(row.createdAt).toBeLessThanOrEqual(after);
+    expect(row.updatedAt).toBe(row.createdAt);
+    expect(row.lastSeenAt).toBe(row.createdAt);
+    // Fresh insert is active (revoked: false) so the cleanup index range
+    // [revoked, updatedAt] covers it, and carries no error code.
+    expect(row.revoked).toBe(false);
+    expect(row.revokedAt).toBeUndefined();
+    expect(row.lastErrorCode).toBeUndefined();
+  });
+
+  test("re-upserting the same token patches the row instead of duplicating, and clears revocation", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId } = await seedAuthedUser(t);
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+
+    // First upsert creates the row.
+    const firstId = await asUser.mutation(api.pushTokens.upsert, {
+      token: "ExponentPushToken[dup]",
+      deviceType: "ios",
+    });
+
+    // Simulate a revoked/dead token the way markRevoked would: set the
+    // tombstone fields and a stale createdAt so we can prove createdAt is
+    // preserved across the patch path while updatedAt/lastSeenAt advance.
+    const stale = Date.now() - 60_000;
+    await t.run(async (ctx) => {
+      await ctx.db.patch(firstId, {
+        createdAt: stale,
+        updatedAt: stale,
+        lastSeenAt: stale,
+        revoked: true,
+        revokedAt: stale,
+        lastErrorCode: "DeviceNotRegistered",
+      });
+    });
+
+    // Second upsert of the SAME token by the SAME user.
+    const before = Date.now();
+    const secondId = await asUser.mutation(api.pushTokens.upsert, {
+      token: "ExponentPushToken[dup]",
+      deviceType: "ios",
+    });
+
+    // Idempotent: same row id back, still exactly one row in the table.
+    expect(secondId).toBe(firstId);
+    const rows = await t.run(async (ctx) => ctx.db.query("pushTokens").collect());
+    expect(rows).toHaveLength(1);
+
+    const row = rows[0];
+    expect(row.userId).toBe(appUserId);
+    // createdAt preserved, updatedAt + lastSeenAt refreshed forward.
+    expect(row.createdAt).toBe(stale);
+    expect(row.updatedAt).toBeGreaterThanOrEqual(before);
+    expect(row.lastSeenAt).toBeGreaterThanOrEqual(before);
+    // Revocation cleared: the same-user patch un-revokes and drops the error.
+    expect(row.revoked).toBe(false);
+    expect(row.revokedAt).toBeUndefined();
+    expect(row.lastErrorCode).toBeUndefined();
+  });
+
+  test("reassigns a token to the current user when it was owned by someone else", async () => {
+    const t = initConvexTest();
+    const owner = await seedAuthedUser(t);
+    const taker = await seedAuthedUser(t);
+
+    const asOwner = t.withIdentity(identityFor(owner.authUserId, owner.sessionId));
+    const asTaker = t.withIdentity(identityFor(taker.authUserId, taker.sessionId));
+
+    // Owner registers the token first.
+    const ownerTokenId = await asOwner.mutation(api.pushTokens.upsert, {
+      token: "ExponentPushToken[shared]",
+      deviceType: "ios",
+    });
+
+    // Same physical token now upserted by a different signed-in user (device
+    // changed hands). Handler reassigns the existing row rather than inserting.
+    const takerTokenId = await asTaker.mutation(api.pushTokens.upsert, {
+      token: "ExponentPushToken[shared]",
+      deviceType: "ios",
+    });
+
+    expect(takerTokenId).toBe(ownerTokenId); // reused, not a new row
+    const rows = await t.run(async (ctx) => ctx.db.query("pushTokens").collect());
+    expect(rows).toHaveLength(1);
+    // Ownership transferred to the taker's app user id.
+    expect(rows[0].userId).toBe(taker.appUserId);
+    expect(rows[0].userId).not.toBe(owner.appUserId);
+  });
+
+  test("throws ConvexError when called without authentication", async () => {
+    const t = initConvexTest();
+    await expect(
+      t.mutation(api.pushTokens.upsert, { token: "ExponentPushToken[anon]", deviceType: "ios" }),
+    ).rejects.toThrowError(ConvexError);
+
+    // And no row leaked into the table from the rejected call.
+    const rows = await t.run(async (ctx) => ctx.db.query("pushTokens").collect());
+    expect(rows).toHaveLength(0);
+  });
+});

package/dist/templates/default/__tests__/convex/users-deleteAccount.test.ts

@@ -0,0 +1,140 @@
+/// <reference types="vite/client" />
+/**
+ * Authenticated convexTest coverage for `users.deleteAccount`.
+ *
+ * `deleteAccount` is an authMutation that soft-deletes the current user:
+ *   - rate-limits on the `criticalAction` bucket (rateLimiter component)
+ *   - drops the user's push tokens so notifications stop
+ *   - revokes Better Auth sessions for the user
+ *   - patches the app users row with `deletedAt`
+ *   - writes a `requested` row to `accountDeletionAudit`
+ *   - is idempotent: a second call no-ops and returns the original deletedAt
+ *
+ * Auth resolution mirrors the proven harness at
+ * __tests__/convex/_auth-harness.test.ts: seed a Better Auth user + unexpired
+ * session in the component db, seed the mirrored app `users` row keyed by
+ * authId, then drive calls with an identity whose subject == better-auth user
+ * id and sessionId == better-auth session id (both REAL component doc ids).
+ */
+import { ConvexError } from "convex/values";
+import { describe, expect, test } from "vitest";
+
+import { api } from "@/convex/_generated/api";
+
+import {
+  auditRowsFor,
+  componentSessionsFor,
+  identityFor,
+  initConvexTest,
+  seedAuthedUser,
+} from "./_harness";
+
+const FAR_FUTURE = Date.now() + 7 * 24 * 60 * 60 * 1000;
+
+describe("users.deleteAccount", () => {
+  test("happy path: tombstones the user, drops push tokens, writes an audit row", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId } = await seedAuthedUser(t);
+
+    // Give the user a push token so we can prove deleteAccount removes it.
+    const tokenNow = Date.now();
+    const pushTokenId = await t.run(async (ctx) =>
+      ctx.db.insert("pushTokens", {
+        userId: appUserId,
+        token: "ExponentPushToken[abc123]",
+        deviceType: "ios",
+        createdAt: tokenNow,
+        updatedAt: tokenNow,
+      }),
+    );
+
+    // Sanity: the row starts un-tombstoned with one live session.
+    const before = await t.run(async (ctx) => ctx.db.get(appUserId));
+    expect(before?.deletedAt).toBeUndefined();
+    expect(await componentSessionsFor(t, authUserId)).toHaveLength(1);
+
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+    const beforeCall = Date.now();
+    const result = await asUser.mutation(api.users.deleteAccount, {});
+    const afterCall = Date.now();
+
+    // Return value: success + a deletedAt timestamp inside the call window.
+    expect(result.success).toBe(true);
+    expect(result.deletedAt).toBeGreaterThanOrEqual(beforeCall);
+    expect(result.deletedAt).toBeLessThanOrEqual(afterCall);
+
+    // Real DB effect: the users row now carries the same deletedAt.
+    const after = await t.run(async (ctx) => ctx.db.get(appUserId));
+    expect(after?.deletedAt).toBe(result.deletedAt);
+    expect(after?.updatedAt).toBe(result.deletedAt);
+
+    // Push token deleted so notifications stop.
+    const tokenGone = await t.run(async (ctx) => ctx.db.get(pushTokenId));
+    expect(tokenGone).toBeNull();
+
+    // Better Auth sessions revoked so the user's other devices are signed out.
+    // Without this assertion, dropping the session-revocation line would leave
+    // every deleteAccount test green.
+    expect(await componentSessionsFor(t, authUserId)).toHaveLength(0);
+
+    // Exactly one "requested" audit row keyed to this user.
+    const audit = await auditRowsFor(t, appUserId);
+    expect(audit).toHaveLength(1);
+    expect(audit[0]!.event).toBe("requested");
+    expect(audit[0]!.authId).toBe(authUserId);
+    expect(audit[0]!.at).toBe(result.deletedAt);
+  });
+
+  test("idempotent: a second call no-ops and does not write a duplicate audit row", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId } = await seedAuthedUser(t);
+
+    const first = await t
+      .withIdentity(identityFor(authUserId, sessionId))
+      .mutation(api.users.deleteAccount, {});
+
+    // deleteAccount revoked every session for this user, so the first
+    // identity no longer resolves. A returning user signs back in within the
+    // grace window (fresh session) before the client retries. Seed that
+    // session and drive the retry through it, same user, already tombstoned.
+    const retryNow = Date.now();
+    const retrySessionId = await t.runInComponent("betterAuth", async (ctx) => {
+      const session = await ctx.db.insert("session", {
+        userId: authUserId,
+        token: `tok_retry_${authUserId}`,
+        expiresAt: FAR_FUTURE,
+        createdAt: retryNow,
+        updatedAt: retryNow,
+      });
+      return session as string;
+    });
+    const asUser = t.withIdentity(identityFor(authUserId, retrySessionId));
+
+    // Second call returns the ORIGINAL deletedAt and touches nothing new.
+    const second = await asUser.mutation(api.users.deleteAccount, {});
+    expect(second.success).toBe(true);
+    expect(second.deletedAt).toBe(first.deletedAt);
+
+    // deletedAt unchanged on the row.
+    const row = await t.run(async (ctx) => ctx.db.get(appUserId));
+    expect(row?.deletedAt).toBe(first.deletedAt);
+
+    // Still exactly one audit row: the no-op path inserts nothing.
+    const audit = await auditRowsFor(t, appUserId);
+    expect(audit).toHaveLength(1);
+    expect(audit[0]!.event).toBe("requested");
+  });
+
+  test("authMutation guard: rejects with ConvexError when unauthenticated", async () => {
+    const t = initConvexTest();
+    // Seed a real user so the table is non-empty; we just never pass identity.
+    const { appUserId } = await seedAuthedUser(t);
+
+    await expect(t.mutation(api.users.deleteAccount, {})).rejects.toThrowError(ConvexError);
+
+    // And the guard ran before any write: the row is untouched, no audit row.
+    const row = await t.run(async (ctx) => ctx.db.get(appUserId));
+    expect(row?.deletedAt).toBeUndefined();
+    expect(await auditRowsFor(t, appUserId)).toHaveLength(0);
+  });
+});

package/dist/templates/default/__tests__/convex/users-deleteAvatar.test.ts

@@ -0,0 +1,104 @@
+/// <reference types="vite/client" />
+/**
+ * Real convexTest coverage for `users.deleteAvatar` (authMutation).
+ *
+ * deleteAvatar (convex/users.ts):
+ *   1. rateLimitWithThrow(ctx, "userAction", ...)   -> needs rateLimiter component
+ *   2. if (ctx.user.avatar) ctx.storage.delete(ctx.user.avatar)
+ *   3. ctx.db.patch(ctx.user._id, { avatar: undefined, updatedAt: now })
+ *   4. return { success: true }
+ *
+ * Auth resolves exactly as the harness in `_auth-harness.test.ts` documents:
+ * better-auth `user` + unexpired `session` rows whose REAL component ids match
+ * identity.subject / identity.sessionId, plus the mirrored app `users` row keyed
+ * by authId. See that file for the full walkthrough.
+ */
+import { ConvexError } from "convex/values";
+import { describe, expect, test } from "vitest";
+
+import { api } from "@/convex/_generated/api";
+
+import { identityFor, initConvexTest, seedAuthedUser } from "./_harness";
+
+describe("users.deleteAvatar", () => {
+  test("clears the avatar field and frees the storage blob", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId } = await seedAuthedUser(t);
+
+    // Store a real avatar blob and attach it to the app users row, then
+    // capture the row's updatedAt so we can prove the patch bumps it.
+    const { storageId, updatedAtBefore } = await t.run(async (ctx) => {
+      const id = await ctx.storage.store(new Blob(["avatar-bytes"], { type: "image/png" }));
+      await ctx.db.patch(appUserId, { avatar: id, updatedAt: 1 });
+      const row = await ctx.db.get(appUserId);
+      return { storageId: id, updatedAtBefore: row!.updatedAt };
+    });
+
+    // Precondition: the blob is actually retrievable before deletion.
+    const urlBefore = await t.run(async (ctx) => ctx.storage.getUrl(storageId));
+    expect(urlBefore).not.toBeNull();
+    expect(updatedAtBefore).toBe(1);
+
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+    const result = await asUser.mutation(api.users.deleteAvatar, {});
+    expect(result).toEqual({ success: true });
+
+    // DB effect: avatar field is cleared and updatedAt moved off the stale 1.
+    const row = await t.run(async (ctx) => ctx.db.get(appUserId));
+    expect(row!.avatar).toBeUndefined();
+    expect(row!.updatedAt).toBeGreaterThan(updatedAtBefore);
+
+    // Storage effect: the blob is gone (deleted ids resolve to a null url).
+    const urlAfter = await t.run(async (ctx) => ctx.storage.getUrl(storageId));
+    expect(urlAfter).toBeNull();
+  });
+
+  test("is a no-op on storage when there is no avatar, still returns success", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId } = await seedAuthedUser(t);
+
+    // Seed an unrelated stored blob to prove the no-avatar path doesn't touch
+    // storage indiscriminately (the `if (ctx.user.avatar)` guard).
+    const bystanderId = await t.run(async (ctx) =>
+      ctx.storage.store(new Blob(["someone-elses-file"], { type: "image/png" })),
+    );
+
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+    const result = await asUser.mutation(api.users.deleteAvatar, {});
+    expect(result).toEqual({ success: true });
+
+    // The users row never had an avatar; it stays cleared.
+    const row = await t.run(async (ctx) => ctx.db.get(appUserId));
+    expect(row!.avatar).toBeUndefined();
+
+    // The unrelated blob is untouched.
+    const bystanderUrl = await t.run(async (ctx) => ctx.storage.getUrl(bystanderId));
+    expect(bystanderUrl).not.toBeNull();
+  });
+
+  test("throws ConvexError when called unauthenticated", async () => {
+    const t = initConvexTest();
+    await seedAuthedUser(t); // data exists; we just don't present an identity
+    await expect(t.mutation(api.users.deleteAvatar, {})).rejects.toThrowError(ConvexError);
+  });
+
+  test("an identity with an expired session is treated as unauthenticated", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId } = await seedAuthedUser(t, {
+      expiresAt: Date.now() - 1000, // already expired
+    });
+
+    // Capture the seeded updatedAt so we can prove no patch ran.
+    const updatedAtBefore = await t.run(async (ctx) => {
+      const row = await ctx.db.get(appUserId);
+      return row!.updatedAt;
+    });
+
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+    await expect(asUser.mutation(api.users.deleteAvatar, {})).rejects.toThrowError(ConvexError);
+
+    // And the row is untouched: no patch ran, so updatedAt is still the seed value.
+    const row = await t.run(async (ctx) => ctx.db.get(appUserId));
+    expect(row!.updatedAt).toBe(updatedAtBefore);
+  });
+});

package/dist/templates/default/__tests__/convex/users-getMe.test.ts

@@ -0,0 +1,98 @@
+/// <reference types="vite/client" />
+/**
+ * Real convexTest coverage for the authed `users.getMe` query.
+ *
+ * `getMe` is an optionalAuthQuery returning the merged AuthUser when authed
+ * (app `users` row + Better Auth name/email/emailVerified) and null otherwise.
+ *
+ * Auth resolves through @convex-dev/better-auth's safeGetAuthUser:
+ *   1. identity = ctx.auth.getUserIdentity()                    (root ctx)
+ *   2. component.adapter.findOne(session) where
+ *        _id == identity.sessionId AND expiresAt > now          (betterAuth db)
+ *   3. component.adapter.findOne(user) where _id == identity.subject
+ *   4. auth.ts getUserByAuthId: app `users` row .withIndex("authId").
+ * The adapter resolves `_id` where-clauses via ctx.db.get, so the identity's
+ * subject/sessionId MUST be the real seeded component doc ids.
+ *
+ * Three seeded rows + one identity drive the authed path:
+ *   - betterAuth `user`    (real id -> identity.subject)
+ *   - betterAuth `session` (real id -> identity.sessionId, expiresAt future)
+ *   - app `users`          (authId == betterAuth user id)
+ */
+import { ConvexError } from "convex/values";
+import { describe, expect, test } from "vitest";
+
+import { api } from "@/convex/_generated/api";
+
+import { identityFor, initConvexTest, seedAuthedUser } from "./_harness";
+
+describe("users.getMe", () => {
+  // HAPPY PATH: authed read returns the merged AuthUser reflecting real DB state.
+  test("returns the merged user from real seeded rows when authenticated", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId, name, email } = await seedAuthedUser(t, {
+      name: "Grace Hopper",
+    });
+    await t.run(async (ctx) => ctx.db.patch(appUserId, { bio: "Compiler pioneer." }));
+
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+    const me = await asUser.query(api.users.getMe, {});
+
+    expect(me).not.toBeNull();
+    // App-owned fields come from the users row we seeded.
+    expect(me!._id).toBe(appUserId);
+    expect(me!.authId).toBe(authUserId);
+    expect(me!.authUserId).toBe(authUserId);
+    expect(me!.bio).toBe("Compiler pioneer.");
+    // Identity fields are merged from the Better Auth user record.
+    expect(me!.name).toBe(name);
+    expect(me!.email).toBe(email);
+    expect(me!.emailVerified).toBe(true);
+    // No uploaded avatar and no provider image -> resolved avatarUrl is null.
+    expect(me!.hasUploadedAvatar).toBe(false);
+    expect(me!.avatarUrl).toBeNull();
+  });
+
+  // GUARD: getMe is optional-auth, so an unauthed call returns null, not a throw,
+  // even though the seeded data exists. Proves the auth lookup actually gates the
+  // result rather than leaking the row to anonymous callers.
+  test("returns null when unauthenticated", async () => {
+    const t = initConvexTest();
+    await seedAuthedUser(t); // data exists; we just don't attach an identity
+    expect(await t.query(api.users.getMe, {})).toBeNull();
+  });
+
+  // GUARD: the session findOne enforces expiresAt > now. An expired session
+  // resolves to no auth user, so getMe falls back to null. This proves the
+  // harness traverses the real session lookup, not just identity.subject.
+  test("returns null when the session is expired", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId } = await seedAuthedUser(t, {
+      expiresAt: Date.now() - 1000, // already expired
+    });
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+    expect(await asUser.query(api.users.getMe, {})).toBeNull();
+  });
+
+  // GUARD on the write path that feeds getMe: updateProfile validates bio length
+  // (max 500). A 501-char bio throws ConvexError(VAL_3001) and must NOT patch the
+  // row, so a follow-up getMe still shows the original bio.
+  test("updateProfile rejects an over-long bio and leaves the row unchanged", async () => {
+    const t = initConvexTest();
+    const { authUserId, sessionId, appUserId } = await seedAuthedUser(t);
+    await t.run(async (ctx) => ctx.db.patch(appUserId, { bio: "original" }));
+    const asUser = t.withIdentity(identityFor(authUserId, sessionId));
+
+    const tooLong = "x".repeat(501);
+    await expect(asUser.mutation(api.users.updateProfile, { bio: tooLong })).rejects.toThrow(
+      ConvexError,
+    );
+
+    // The patch never ran: the persisted bio is untouched.
+    const row = await t.run(async (ctx) => ctx.db.get(appUserId));
+    expect(row?.bio).toBe("original");
+    // And it surfaces unchanged through the authed read path.
+    const me = await asUser.query(api.users.getMe, {});
+    expect(me!.bio).toBe("original");
+  });
+});

package/dist/templates/default/__tests__/convex/users-getUser.test.ts

@@ -0,0 +1,120 @@
+/// <reference types="vite/client" />
+/**
+ * Real convexTest coverage for `api.users.getUser` (optionalAuthQuery).
+ *
+ * getUser merges an app `users` row with its Better Auth identity record:
+ *   1. ctx.db.normalizeId("users", userId)  -> null on malformed input
+ *   2. ctx.db.get(id)                         -> null when the app row is gone
+ *   3. authComponent.getAnyUserById(authId)   -> null when the auth record is gone
+ *   4. returns { _id, _creationTime, name, username, avatarUrl, bio }
+ *      name/username come from Better Auth; bio from the app row; avatarUrl
+ *      falls back to the Better Auth `image` when no uploaded avatar exists.
+ *
+ * Auth seeding uses the shared harness (./_harness): seed a Better Auth `user`
+ * + unexpired `session` and the mirrored app `users` row, then patch in the
+ * identity fields getUser merges (bio on the app row; image/username/
+ * displayUsername on the Better Auth record) using the returned ids.
+ */
+import { describe, expect, test } from "vitest";
+
+import { api } from "@/convex/_generated/api";
+
+import { identityFor, initConvexTest, seedAuthedUser, type AuthedTest } from "./_harness";
+
+/** Patch Better Auth identity fields (image/username/displayUsername) onto a seeded user. */
+async function patchAuthFields(
+  t: AuthedTest,
+  authUserId: string,
+  fields: { image?: string; username?: string; displayUsername?: string },
+) {
+  await t.runInComponent("betterAuth", async (ctx) => {
+    const db = ctx.db as unknown as {
+      patch: (id: string, doc: Record<string, unknown>) => Promise<void>;
+    };
+    await db.patch(authUserId, fields);
+  });
+}
+
+describe("api.users.getUser", () => {
+  test("returns the merged profile for an existing user (authed caller)", async () => {
+    const t = initConvexTest();
+
+    // Caller is one authed user; they fetch a different target user's profile.
+    const caller = await seedAuthedUser(t, {
+      name: "Caller One",
+      email: "caller@example.com",
+    });
+
+    const target = await seedAuthedUser(t, {
+      name: "Grace Hopper",
+      email: "grace@example.com",
+    });
+    // bio lives on the app row; image/username/displayUsername on the auth record.
+    await t.run(async (ctx) => ctx.db.patch(target.appUserId, { bio: "Compiler pioneer." }));
+    await patchAuthFields(t, target.authUserId, {
+      image: "https://cdn.example.com/grace.png",
+      username: "ghopper",
+      displayUsername: "GraceH",
+    });
+
+    const asCaller = t.withIdentity(identityFor(caller.authUserId, caller.sessionId));
+    const profile = await asCaller.query(api.users.getUser, {
+      userId: target.appUserId,
+    });
+
+    expect(profile).not.toBeNull();
+    // _id is the app users row id, not the Better Auth id.
+    expect(profile!._id).toBe(target.appUserId);
+    // name comes from the Better Auth record, not the app row.
+    expect(profile!.name).toBe(target.name);
+    // username prefers displayUsername over username.
+    expect(profile!.username).toBe("GraceH");
+    // bio comes from the app users row.
+    expect(profile!.bio).toBe("Compiler pioneer.");
+    // No uploaded avatar -> falls back to the Better Auth image.
+    expect(profile!.avatarUrl).toBe("https://cdn.example.com/grace.png");
+    expect(typeof profile!._creationTime).toBe("number");
+  });
+
+  test("username falls back to `username` when displayUsername is absent", async () => {
+    const t = initConvexTest();
+    const target = await seedAuthedUser(t, {
+      name: "No Display Name",
+    });
+    await patchAuthFields(t, target.authUserId, {
+      username: "plainuser",
+      // displayUsername intentionally omitted
+    });
+
+    const profile = await t.query(api.users.getUser, { userId: target.appUserId });
+    expect(profile).not.toBeNull();
+    expect(profile!.username).toBe("plainuser");
+    // No image and no avatar -> null.
+    expect(profile!.avatarUrl).toBeNull();
+  });
+
+  test("returns null for a malformed user id (normalizeId miss)", async () => {
+    const t = initConvexTest();
+    // Seed a real user so the table exists, then ask for a garbage id.
+    await seedAuthedUser(t);
+    const profile = await t.query(api.users.getUser, {
+      userId: "not-a-valid-convex-id",
+    });
+    expect(profile).toBeNull();
+  });
+
+  test("returns null when the app users row was deleted (ctx.db.get miss)", async () => {
+    const t = initConvexTest();
+    const target = await seedAuthedUser(t);
+
+    // Capture a well-formed id, then delete the row so normalizeId succeeds
+    // but the get() misses. This proves the guard is the missing-row branch,
+    // not a malformed-id rejection.
+    await t.run(async (ctx) => ctx.db.delete(target.appUserId));
+
+    const profile = await t.query(api.users.getUser, {
+      userId: target.appUserId,
+    });
+    expect(profile).toBeNull();
+  });
+});

package/dist/templates/default/__tests__/convex/users-hardDeleteExpired.test.ts

@@ -0,0 +1,67 @@
+/// <reference types="vite/client" />
+/**
+ * convexTest coverage for `internal.users.hardDeleteExpired`, the irreversible
+ * 30-day account purge (the highest-stakes data-loss path in the template).
+ *
+ * It scans the `by_deletedAt` index for tombstoned users past the grace window
+ * and permanently purges them. The index is on the OPTIONAL `deletedAt` field,
+ * and Convex sorts `undefined < null < numbers`, so an unbounded scan returns
+ * every ACTIVE user (deletedAt unset) before any tombstone. These tests seed
+ * MORE active users than the batch size: a regression to an unbounded scan
+ * would starve the tombstone and purge nothing, failing the first test.
+ */
+import { describe, expect, test } from "vitest";
+
+import { internal } from "@/convex/_generated/api";
+import { ACCOUNT_DELETION_GRACE_MS } from "@/convex/users";
+
+import { auditRowsFor, initConvexTest, seedAuthedUser } from "./_harness";
+
+const HARD_DELETE_BATCH = 50;
+
+describe("users.hardDeleteExpired", () => {
+  test("purges only tombstones past the grace window, even behind a full batch of active users", async () => {
+    const t = initConvexTest();
+    const now = Date.now();
+
+    // Active (deletedAt unset) users filling the batch. Under an unbounded
+    // `by_deletedAt` scan these sort ahead of any tombstone and crowd it out.
+    await t.run(async (ctx) => {
+      for (let i = 0; i < HARD_DELETE_BATCH; i++) {
+        await ctx.db.insert("users", { authId: `active_${i}`, createdAt: now, updatedAt: now });
+      }
+    });
+
+    const expired = await seedAuthedUser(t, {
+      deletedAt: now - ACCOUNT_DELETION_GRACE_MS - 60_000,
+      email: "expired@example.com",
+    });
+    const inGrace = await seedAuthedUser(t, {
+      deletedAt: now - 60_000,
+      email: "ingrace@example.com",
+    });
+
+    const purged = await t.mutation(internal.users.hardDeleteExpired, {});
+    expect(purged).toBe(1);
+
+    // Expired tombstone: a "permanent" audit row was written.
+    const expiredAudit = await auditRowsFor(t, expired.appUserId);
+    expect(expiredAudit.some((r) => r.event === "permanent")).toBe(true);
+
+    // In-grace tombstone: untouched, no permanent purge.
+    const inGraceRow = await t.run(async (ctx) => ctx.db.get(inGrace.appUserId));
+    expect(inGraceRow?.deletedAt).toBe(now - 60_000);
+    const inGraceAudit = await auditRowsFor(t, inGrace.appUserId);
+    expect(inGraceAudit.some((r) => r.event === "permanent")).toBe(false);
+  });
+
+  test("purges nothing when every tombstone is still inside the grace window", async () => {
+    const t = initConvexTest();
+    const now = Date.now();
+    await seedAuthedUser(t, { deletedAt: now - 60_000, email: "recent@example.com" });
+    await seedAuthedUser(t, { email: "active@example.com" }); // not tombstoned
+
+    const purged = await t.mutation(internal.users.hardDeleteExpired, {});
+    expect(purged).toBe(0);
+  });
+});