@sixb/core 0.1.20 → 0.1.22

package/src/testing/auth-storage-contract.ts

@@ -3,6 +3,9 @@ import type {
   AuthStorage,
   AuthStorageErrorCode,
   CompleteAuthSessionInput,
+  CompleteSignInResult,
+  ListAuthUsersInput,
+  UpdateAuthUserResult,
   UserRecord,
 } from "../storage/auth"
 import { AuthStorageError } from "../storage/auth"
@@ -12,6 +15,20 @@ export interface AuthStorageContractSuiteOptions<TStorage extends AuthStorage =
   readonly createStorage: () => TStorage | Promise<TStorage>
   /** Optional cleanup invoked after every test case. */
   readonly teardown?: (storage: TStorage) => void | Promise<void>
+  /**
+   * Locks a user's row as a concurrent writer would, for stores whose updates can run side by side.
+   * Without it, concurrent updates run unforced, which is enough for a store that serializes them.
+   */
+  readonly holdUser?: (
+    storage: TStorage,
+    user: { readonly projectId: string; readonly id: string }
+  ) => Promise<AuthUserHold>
+}
+
+export interface AuthUserHold {
+  /** Resolves once `count` writers wait on the hold, or once `competing` settles without waiting. */
+  readonly waitForWaiters: (count: number, competing: Promise<unknown>) => Promise<void>
+  readonly release: () => Promise<void>
 }
 
 const projectId = "project-a"
@@ -80,13 +97,14 @@ async function createUser(
 
 async function completeOidcSignInForAva(
   storage: AuthStorage,
-  directoryGroupIds: readonly string[] | undefined
+  directoryGroupIds: readonly string[] | undefined,
+  attempt: string
 ): Promise<void> {
   await storage.oidcAuthorizationAttempts.create({
-    id: "oidc_directory",
+    id: `oidc_${attempt}`,
     projectId,
     strategyId: "entra",
-    stateHash: "directory-state",
+    stateHash: `${attempt}-state`,
     nonceHash: "nonce-hash",
     codeVerifier: "verifier",
     createdAt: at("2026-05-14T10:00:00.000Z"),
@@ -94,17 +112,60 @@ async function completeOidcSignInForAva(
   })
   await storage.completeOidcSignIn({
     projectId,
-    oidcAuthorizationAttemptId: "oidc_directory",
-    stateHash: "directory-state",
+    oidcAuthorizationAttemptId: `oidc_${attempt}`,
+    stateHash: `${attempt}-state`,
     completedAt: at("2026-05-14T10:01:00.000Z"),
     subject: "entra-ava",
     email: "ava@acme.com",
     directoryGroupIds,
     newUserId: "usr_unused",
-    session: sessionInput("ses_directory"),
+    session: sessionInput(`ses_${attempt}`),
   })
 }
 
+// Signs Ava in through the "okta" provider with the profile it sends.
+async function signInWithOidcProfile(
+  storage: AuthStorage,
+  input: {
+    readonly attemptId: string
+    readonly completedAt: string
+    readonly displayName?: string
+    readonly avatarUrl?: string
+  }
+): Promise<CompleteSignInResult> {
+  await storage.oidcAuthorizationAttempts.create({
+    id: input.attemptId,
+    projectId,
+    strategyId: "okta",
+    stateHash: `${input.attemptId}-state`,
+    nonceHash: "nonce-hash",
+    codeVerifier: "verifier",
+    createdAt: at("2026-05-14T10:00:00.000Z"),
+    expiresAt: at("2026-05-14T11:00:00.000Z"),
+  })
+
+  return storage.completeOidcSignIn({
+    projectId,
+    oidcAuthorizationAttemptId: input.attemptId,
+    stateHash: `${input.attemptId}-state`,
+    completedAt: at(input.completedAt),
+    subject: "00u1",
+    email: "ava@acme.com",
+    displayName: input.displayName,
+    avatarUrl: input.avatarUrl,
+    newUserId: "usr_unused",
+    session: sessionInput(`ses_${input.attemptId}`),
+  })
+}
+
+/** Two concurrent updates of one user, in the order they committed: the later found the earlier. */
+function inCommitOrder(
+  a: UpdateAuthUserResult,
+  b: UpdateAuthUserResult
+): readonly [UpdateAuthUserResult, UpdateAuthUserResult] {
+  return Bun.deepEquals(b.previousUser, a.user) ? [a, b] : [b, a]
+}
+
 /**
  * Runs the shared `AuthStorage` contract against any storage implementation.
  *
@@ -125,6 +186,33 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
     }
   }
 
+  /**
+   * Runs two updates of usr_1 at once. With a hold, both wait behind it, the first queued first,
+   * so each reads only after the other could have written.
+   */
+  const race = async (
+    storage: TStorage,
+    first: () => Promise<UpdateAuthUserResult>,
+    second: () => Promise<UpdateAuthUserResult>
+  ): Promise<UpdateAuthUserResult[]> => {
+    const hold = await options.holdUser?.(storage, { projectId, id: "usr_1" })
+    if (!hold) return Promise.all([first(), second()])
+
+    let updates: Promise<UpdateAuthUserResult>[] = []
+    try {
+      const a = first()
+      updates = [a]
+      await hold.waitForWaiters(1, a)
+
+      const b = second()
+      updates = [a, b]
+      await hold.waitForWaiters(2, b)
+    } finally {
+      await hold.release()
+    }
+    return Promise.all(updates)
+  }
+
   describe(label, () => {
     test("creates users with normalized email and isolates projects", async () => {
       await withStorage(async (storage) => {
@@ -160,6 +248,82 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
       })
     })
 
+    test("reads users by id in one call, skipping unknown ids and other projects", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage, { id: "usr_ava", email: "ava@acme.com" })
+        await createUser(storage, { id: "usr_ben", email: "ben@acme.com", status: "suspended" })
+        await createUser(storage, {
+          id: "usr_other",
+          email: "cleo@acme.com",
+          projectId: otherProjectId,
+        })
+
+        const users = await storage.users.getByIds({
+          projectId,
+          ids: ["usr_ben", "usr_missing", "usr_ava", "usr_other", "usr_ava"],
+        })
+
+        const byId = [...users].sort((a, b) => a.id.localeCompare(b.id))
+        expect(byId.map((user) => [user.id, user.email, user.status])).toEqual([
+          ["usr_ava", "ava@acme.com", "active"],
+          ["usr_ben", "ben@acme.com", "suspended"],
+        ])
+        expect(byId[0]?.createdAt).toEqual(at("2026-05-14T10:00:00.000Z"))
+
+        expect(await storage.users.getByIds({ projectId, ids: [] })).toEqual([])
+      })
+    })
+
+    test("searches users by display name or email, ignoring case", async () => {
+      await withStorage(async (storage) => {
+        const people = [
+          { id: "usr_ava", email: "ava@acme.com", displayName: "Ava Martin" },
+          { id: "usr_ben", email: "ben@martin-family.org", displayName: "Ben Okafor" },
+          { id: "usr_cleo", email: "cleo@acme.com", status: "suspended" as const },
+          { id: "usr_dan", email: "dan@acme.com", displayName: "Dan 100%_sure" },
+          { id: "usr_emilie", email: "emilie@roy.fr", displayName: "Émilie Roy" },
+        ]
+        for (const [index, person] of people.entries()) {
+          await storage.users.create({
+            ...person,
+            projectId,
+            createdAt: at(`2026-05-14T10:0${index}:00.000Z`),
+          })
+        }
+        await storage.users.create({
+          id: "usr_other",
+          projectId: otherProjectId,
+          email: "martin@acme.com",
+          createdAt: at("2026-05-14T10:09:00.000Z"),
+        })
+
+        const ids = async (input: Omit<ListAuthUsersInput, "projectId">) => {
+          const page = await storage.users.list({ projectId, order: "asc", ...input })
+          return page.users.map((row) => row.id)
+        }
+
+        // A name, an email, either side of the match, and no other project.
+        expect(await ids({ search: "MARTIN" })).toEqual(["usr_ava", "usr_ben"])
+        expect(await ids({ search: "@acme" })).toEqual(["usr_ava", "usr_cleo", "usr_dan"])
+        expect(await ids({ search: "Cleo" })).toEqual(["usr_cleo"])
+        expect(await ids({ search: "cleo", statuses: ["active"] })).toEqual([])
+
+        // Text outside ASCII matches as typed, on every provider.
+        expect(await ids({ search: "Émilie" })).toEqual(["usr_emilie"])
+        expect(await ids({ search: "milie R" })).toEqual(["usr_emilie"])
+
+        // Wildcard characters are plain text.
+        expect(await ids({ search: "%" })).toEqual(["usr_dan"])
+        expect(await ids({ search: "0%_s" })).toEqual(["usr_dan"])
+        expect(await ids({ search: "_" })).toEqual(["usr_dan"])
+
+        const page = await storage.users.list({ projectId, search: "acme", limit: 2, order: "asc" })
+        expect(page.users.map((row) => row.id)).toEqual(["usr_ava", "usr_cleo"])
+        expect(page.total).toBe(3)
+        expect(page.hasMore).toBe(true)
+      })
+    })
+
     test("upserts identities without mutating canonical user email", async () => {
       await withStorage(async (storage) => {
         await createUser(storage, { id: "usr_oidc", email: "ava@acme.com" })
@@ -188,6 +352,203 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
       })
     })
 
+    // To see this fail, write both columns from the input as given.
+    test("updates only the profile fields given, and clears one set to null", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+        await storage.users.updateProfile({
+          projectId,
+          id: "usr_1",
+          displayName: "Ava Lovelace",
+          avatarUrl: "https://images.acme.com/ava.png",
+          updatedAt: at("2026-05-14T10:01:00.000Z"),
+        })
+
+        const renamed = await storage.users.updateProfile({
+          projectId,
+          id: "usr_1",
+          displayName: "Ava King",
+          updatedAt: at("2026-05-14T10:02:00.000Z"),
+        })
+        expect(renamed.user).toMatchObject({
+          displayName: "Ava King",
+          avatarUrl: "https://images.acme.com/ava.png",
+          updatedAt: at("2026-05-14T10:02:00.000Z"),
+        })
+
+        const cleared = await storage.users.updateProfile({
+          projectId,
+          id: "usr_1",
+          avatarUrl: null,
+          updatedAt: at("2026-05-14T10:03:00.000Z"),
+        })
+        expect(cleared.user.displayName).toBe("Ava King")
+        expect(cleared.user.avatarUrl).toBeUndefined()
+        await expect(storage.users.getById({ projectId, id: "usr_1" })).resolves.toEqual(
+          cleared.user
+        )
+
+        await expectAuthError(
+          storage.users.updateProfile({ projectId, id: "usr_missing", displayName: "Nobody" }),
+          "missing_user"
+        )
+      })
+    })
+
+    // To see this fail, return the user as updated in place of the user before the update.
+    test("returns the user as a profile update found them", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+
+        const named = await storage.users.updateProfile({
+          projectId,
+          id: "usr_1",
+          displayName: "Ava Lovelace",
+          updatedAt: at("2026-05-14T10:01:00.000Z"),
+        })
+        expect(named.previousUser).toMatchObject({
+          id: "usr_1",
+          updatedAt: at("2026-05-14T10:00:00.000Z"),
+        })
+        expect(named.previousUser.displayName).toBeUndefined()
+
+        const renamed = await storage.users.updateProfile({
+          projectId,
+          id: "usr_1",
+          displayName: "Ava King",
+          updatedAt: at("2026-05-14T10:02:00.000Z"),
+        })
+        expect(renamed.previousUser).toEqual(named.user)
+      })
+    })
+
+    // To see this fail, write the profile even when the values it is given are the stored ones.
+    test("leaves a profile alone when an update gives it the values it has", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+        const named = await storage.users.updateProfile({
+          projectId,
+          id: "usr_1",
+          displayName: "Ava Lovelace",
+          updatedAt: at("2026-05-14T10:01:00.000Z"),
+        })
+
+        const unchanged = await storage.users.updateProfile({
+          projectId,
+          id: "usr_1",
+          displayName: "Ava Lovelace",
+          avatarUrl: null,
+          updatedAt: at("2026-05-14T10:02:00.000Z"),
+        })
+
+        expect(unchanged).toEqual({ user: named.user, previousUser: named.user })
+        await expect(storage.users.getById({ projectId, id: "usr_1" })).resolves.toEqual(named.user)
+      })
+    })
+
+    // To see this fail, return the updated user as the previous one.
+    test("returns the user as a status change found them", async () => {
+      await withStorage(async (storage) => {
+        const ava = await createUser(storage)
+
+        const suspended = await storage.users.updateStatus({
+          projectId,
+          id: "usr_1",
+          status: "suspended",
+          updatedAt: at("2026-05-14T10:01:00.000Z"),
+        })
+        expect(suspended.user).toMatchObject({
+          status: "suspended",
+          updatedAt: at("2026-05-14T10:01:00.000Z"),
+        })
+        expect(suspended.previousUser).toEqual(ava)
+
+        const reactivated = await storage.users.updateStatus({
+          projectId,
+          id: "usr_1",
+          status: "active",
+          updatedAt: at("2026-05-14T10:02:00.000Z"),
+        })
+        expect(reactivated.previousUser).toEqual(suspended.user)
+
+        await expectAuthError(
+          storage.users.updateStatus({ projectId, id: "usr_missing", status: "active" }),
+          "missing_user"
+        )
+      })
+    })
+
+    // To see this fail on PostgreSQL, pass `forUpdate: false` to `getUserRowById` in
+    // `updateStatus` (`storage/pg/src/auth-storage/users.ts`): both changes then report Ava active.
+    test("chains the previous users of concurrent status changes", async () => {
+      await withStorage(async (storage) => {
+        const ava = await createUser(storage)
+
+        const [a, b] = await race(
+          storage,
+          () =>
+            storage.users.updateStatus({
+              projectId,
+              id: "usr_1",
+              status: "suspended",
+              updatedAt: at("2026-05-14T10:01:00.000Z"),
+            }),
+          () =>
+            storage.users.updateStatus({
+              projectId,
+              id: "usr_1",
+              status: "active",
+              updatedAt: at("2026-05-14T10:02:00.000Z"),
+            })
+        )
+
+        const [first, second] = inCommitOrder(a, b)
+        expect(first.previousUser).toEqual(ava)
+        expect(second.previousUser).toEqual(first.user)
+        await expect(storage.users.getById({ projectId, id: "usr_1" })).resolves.toEqual(
+          second.user
+        )
+      })
+    })
+
+    // To see this fail on PostgreSQL, pass `forUpdate: false` to `getUserRowById` in
+    // `updateProfile` (`storage/pg/src/auth-storage/users.ts`): the second update then reports
+    // Ava unnamed.
+    test("chains the previous users of concurrent profile updates, keeping both fields", async () => {
+      await withStorage(async (storage) => {
+        const ava = await createUser(storage)
+
+        const [a, b] = await race(
+          storage,
+          () =>
+            storage.users.updateProfile({
+              projectId,
+              id: "usr_1",
+              displayName: "Ava Lovelace",
+              updatedAt: at("2026-05-14T10:01:00.000Z"),
+            }),
+          () =>
+            storage.users.updateProfile({
+              projectId,
+              id: "usr_1",
+              avatarUrl: "https://acme.com/ava.png",
+              updatedAt: at("2026-05-14T10:02:00.000Z"),
+            })
+        )
+
+        const [first, second] = inCommitOrder(a, b)
+        expect(first.previousUser).toEqual(ava)
+        expect(second.previousUser).toEqual(first.user)
+        expect(second.user).toMatchObject({
+          displayName: "Ava Lovelace",
+          avatarUrl: "https://acme.com/ava.png",
+        })
+        await expect(storage.users.getById({ projectId, id: "usr_1" })).resolves.toEqual(
+          second.user
+        )
+      })
+    })
+
     test("keeps multiple concurrent sessions per user and never extends expiry on touch", async () => {
       await withStorage(async (storage) => {
         await createUser(storage)
@@ -292,6 +653,53 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
       })
     })
 
+    test("lists all of a user's sessions, revoked and expired ones too, newest first", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+        await createUser(storage, { id: "usr_2", email: "ben@acme.com" })
+
+        const session = (id: string, createdAt: string, userId = "usr_1") =>
+          storage.sessions.create({
+            id,
+            projectId,
+            userId,
+            strategyId: "magic-link",
+            tokenHash: `hash-${id}`,
+            createdAt: at(createdAt),
+            expiresAt: at("2026-05-15T10:00:00.000Z"),
+          })
+
+        await session("ses_oldest", "2026-05-14T10:00:00.000Z")
+        await session("ses_revoked", "2026-05-14T10:01:00.000Z")
+        // Created at the same instant as the one above: the cursor skips within the tie.
+        await session("ses_also", "2026-05-14T10:01:00.000Z")
+        await session("ses_newest", "2026-05-14T10:02:00.000Z")
+        await session("ses_other", "2026-05-14T10:03:00.000Z", "usr_2")
+        await storage.sessions.revoke({
+          projectId,
+          id: "ses_revoked",
+          revokedAt: at("2026-05-14T10:05:00.000Z"),
+        })
+
+        const first = await storage.sessions.listByUserId({ projectId, userId: "usr_1", limit: 2 })
+        expect(first.hasMore).toBe(true)
+        expect(first.sessions.map((entry) => entry.id)).toEqual(["ses_newest", "ses_revoked"])
+        expect(first.sessions[1]?.revokedAt?.toISOString()).toBe("2026-05-14T10:05:00.000Z")
+
+        const rest = await storage.sessions.listByUserId({
+          projectId,
+          userId: "usr_1",
+          limit: 2,
+          before: { createdAt: at("2026-05-14T10:01:00.000Z"), skip: 1 },
+        })
+        expect(rest.hasMore).toBe(false)
+        expect(rest.sessions.map((entry) => entry.id)).toEqual(["ses_also", "ses_oldest"])
+        await expect(
+          storage.sessions.listByUserId({ projectId: otherProjectId, userId: "usr_1", limit: 2 })
+        ).resolves.toEqual({ sessions: [], hasMore: false })
+      })
+    })
+
     test("persists and enforces an optional absolute session deadline", async () => {
       await withStorage(async (storage) => {
         await createUser(storage)
@@ -581,7 +989,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
       })
     })
 
-    test("upserts group memberships idempotently and preserves source", async () => {
+    test("upserts group memberships idempotently, preserves source, and requires the user", async () => {
       await withStorage(async (storage) => {
         await createUser(storage)
 
@@ -604,11 +1012,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
         await expect(
           storage.groupMemberships.listForUser({ projectId, userId: "usr_1" })
         ).resolves.toHaveLength(1)
-      })
-    })
 
-    test("rejects group memberships for missing users", async () => {
-      await withStorage(async (storage) => {
         await expectAuthError(
           storage.groupMemberships.upsert({
             projectId,
@@ -622,7 +1026,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
       })
     })
 
-    test("removes group memberships and is idempotent for missing rows", async () => {
+    test("removes group memberships and is idempotent for missing rows and users", async () => {
       await withStorage(async (storage) => {
         await createUser(storage)
 
@@ -649,15 +1053,10 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           storage.groupMemberships.listForUser({ projectId, userId: "usr_1" })
         ).resolves.toHaveLength(0)
 
-        // Removing an already-removed membership is a no-op that returns null.
+        // Removing an already-removed membership, or one of a missing user, returns null.
         await expect(
           storage.groupMemberships.remove({ projectId, userId: "usr_1", groupId: "commercial" })
         ).resolves.toBeNull()
-      })
-    })
-
-    test("returns null when removing a membership for a missing user", async () => {
-      await withStorage(async (storage) => {
         await expect(
           storage.groupMemberships.remove({
             projectId,
@@ -743,11 +1142,6 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           serviceAccounts: [{ id: "svc_ingest" }],
           total: 1,
         })
-      })
-    })
-
-    test("rejects service account memberships for missing service accounts", async () => {
-      await withStorage(async (storage) => {
         await expectAuthError(
           storage.serviceAccountGroupMemberships.upsert({
             projectId,
@@ -1331,6 +1725,57 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
       })
     })
 
+    test("starts a cookie session for a browser that another one approves", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+        await storage.sessions.create({
+          ...bearerSessionInput("ses_browser"),
+          tokenHash: "session-hash",
+          bearer: undefined,
+        })
+        await storage.deviceAuthorizations.create({
+          id: "dva_1",
+          projectId,
+          deviceCodeHash: "device-code-hash",
+          userCode: "BCDF-HJKM",
+          clientName: "Acme viewer",
+          createdAt: at("2026-05-14T10:00:00.000Z"),
+          expiresAt: at("2026-05-14T10:10:00.000Z"),
+        })
+        await storage.deviceAuthorizations.approve({
+          projectId,
+          id: "dva_1",
+          userId: "usr_1",
+          sessionId: "ses_browser",
+          approvedAt: at("2026-05-14T10:01:00.000Z"),
+        })
+
+        const completed = await storage.completeDeviceAuthorization({
+          projectId,
+          id: "dva_1",
+          deviceCodeHash: "device-code-hash",
+          completedAt: at("2026-05-14T10:02:00.000Z"),
+          session: {
+            ...bearerSessionInput("ses_viewer"),
+            tokenHash: "viewer-hash",
+            bearer: undefined,
+          },
+        })
+
+        expect(completed.authorization).toMatchObject({ status: "consumed" })
+        expect(completed.session).toMatchObject({ id: "ses_viewer", userId: "usr_1" })
+        expect(completed.session.bearer).toBeUndefined()
+        await expect(
+          storage.sessions.findValidByTokenHash({
+            projectId,
+            id: "ses_viewer",
+            tokenHash: "viewer-hash",
+            now: at("2026-05-14T10:05:00.000Z"),
+          })
+        ).resolves.toMatchObject({ id: "ses_viewer" })
+      })
+    })
+
     test("keeps bearer and cookie session credentials apart", async () => {
       await withStorage(async (storage) => {
         await createUser(storage)
@@ -1439,7 +1884,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
 
     test("completes magic-link sign-in for an existing user", async () => {
       await withStorage(async (storage) => {
-        await createUser(storage)
+        const ava = await createUser(storage)
         await storage.sessions.create({
           id: "ses_old",
           projectId,
@@ -1469,6 +1914,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
         })
 
         expect(result.user.id).toBe("usr_1")
+        expect(result.previousUser).toEqual(ava)
         expect(result.session).toMatchObject({
           id: "ses_new",
           strategyId: "magic-link",
@@ -1527,6 +1973,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           id: "inv_1",
           status: "accepted",
         })
+        expect(result.previousUser).toBeNull()
         const memberships = await storage.groupMemberships.listForUser({
           projectId,
           userId: "usr_new",
@@ -1696,7 +2143,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
 
     test("completes OIDC sign-in through an existing identity", async () => {
       await withStorage(async (storage) => {
-        await createUser(storage, { id: "usr_oidc", email: "ava@acme.com" })
+        const ava = await createUser(storage, { id: "usr_oidc", email: "ava@acme.com" })
         await storage.identities.upsert({
           projectId,
           strategyId: "okta",
@@ -1728,6 +2175,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           session: sessionInput("ses_oidc"),
         })
 
+        expect(result.previousUser).toEqual(ava)
         expect(result.identity).toMatchObject({
           strategyId: "okta",
           subject: "00u1",
@@ -1771,6 +2219,110 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
       })
     })
 
+    // To see these fail, return the stored user unchanged from the storage's OIDC sign-in.
+    test("refreshes the profile the provider sends on every OIDC sign-in", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+
+        // The first sign-in links Ava by her email, the second finds her identity.
+        const { user: linked } = await signInWithOidcProfile(storage, {
+          attemptId: "oidc_1",
+          completedAt: "2026-05-14T10:01:00.000Z",
+          displayName: "Ava Lovelace",
+          avatarUrl: "https://images.acme.com/ava-1.png",
+        })
+        expect(linked).toMatchObject({
+          id: "usr_1",
+          displayName: "Ava Lovelace",
+          avatarUrl: "https://images.acme.com/ava-1.png",
+          updatedAt: at("2026-05-14T10:01:00.000Z"),
+        })
+
+        const refreshed = await signInWithOidcProfile(storage, {
+          attemptId: "oidc_2",
+          completedAt: "2026-05-14T10:02:00.000Z",
+          displayName: "Ava King",
+          avatarUrl: "https://images.acme.com/ava-2.png",
+        })
+        // The sign-in also says what it changed: it returns the user as it found them.
+        expect(refreshed.previousUser).toEqual(linked)
+        await expect(storage.users.getById({ projectId, id: "usr_1" })).resolves.toMatchObject({
+          displayName: "Ava King",
+          avatarUrl: "https://images.acme.com/ava-2.png",
+          updatedAt: at("2026-05-14T10:02:00.000Z"),
+        })
+      })
+    })
+
+    test("keeps the profile fields the provider leaves out", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+        await signInWithOidcProfile(storage, {
+          attemptId: "oidc_1",
+          completedAt: "2026-05-14T10:01:00.000Z",
+          displayName: "Ava Lovelace",
+          avatarUrl: "https://images.acme.com/ava.png",
+        })
+
+        const { user } = await signInWithOidcProfile(storage, {
+          attemptId: "oidc_2",
+          completedAt: "2026-05-14T10:02:00.000Z",
+        })
+
+        expect(user).toMatchObject({
+          displayName: "Ava Lovelace",
+          avatarUrl: "https://images.acme.com/ava.png",
+        })
+      })
+    })
+
+    test("leaves updatedAt alone when the provider sends the same profile", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+        const profile = {
+          displayName: "Ava Lovelace",
+          avatarUrl: "https://images.acme.com/ava.png",
+        }
+        await signInWithOidcProfile(storage, {
+          attemptId: "oidc_1",
+          completedAt: "2026-05-14T10:01:00.000Z",
+          ...profile,
+        })
+
+        const { user } = await signInWithOidcProfile(storage, {
+          attemptId: "oidc_2",
+          completedAt: "2026-05-14T10:02:00.000Z",
+          ...profile,
+        })
+
+        expect(user.updatedAt).toEqual(at("2026-05-14T10:01:00.000Z"))
+        await expect(storage.users.getById({ projectId, id: "usr_1" })).resolves.toMatchObject({
+          updatedAt: at("2026-05-14T10:01:00.000Z"),
+        })
+      })
+    })
+
+    test("leaves a suspended user's profile alone when their OIDC sign-in is refused", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage, { status: "suspended" })
+
+        await expectAuthError(
+          signInWithOidcProfile(storage, {
+            attemptId: "oidc_1",
+            completedAt: "2026-05-14T10:01:00.000Z",
+            displayName: "Ava Lovelace",
+            avatarUrl: "https://images.acme.com/ava.png",
+          }),
+          "suspended_user"
+        )
+
+        const user = await storage.users.getById({ projectId, id: "usr_1" })
+        expect(user?.displayName).toBeUndefined()
+        expect(user?.avatarUrl).toBeUndefined()
+        expect(user?.updatedAt).toEqual(at("2026-05-14T10:00:00.000Z"))
+      })
+    })
+
     test("creates new OIDC users through active invitations and applies groups", async () => {
       await withStorage(async (storage) => {
         await storage.invitations.createOrUpdateActive({
@@ -1809,6 +2361,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           email: "ava@acme.com",
           displayName: "Ava Chen",
         })
+        expect(result.previousUser).toBeNull()
         expect(result.invitation).toMatchObject({
           id: "inv_oidc",
           status: "accepted",
@@ -1902,65 +2455,35 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
         ] as const) {
           await storage.groupMemberships.upsert({ projectId, userId: "usr_1", groupId, source })
         }
+        const memberships = () =>
+          storage.groupMemberships.listForUser({ projectId, userId: "usr_1" })
 
-        await completeOidcSignInForAva(storage, ["security-admins", "field-ops"])
-
+        await completeOidcSignInForAva(storage, ["security-admins", "field-ops"], "granted")
         // legacy-team is no longer granted; security-admins keeps its manual source.
-        await expect(
-          storage.groupMemberships.listForUser({ projectId, userId: "usr_1" })
-        ).resolves.toMatchObject([
+        const granted = [
           { groupId: "commercial", source: "invitation" },
           { groupId: "field-ops", source: "directory" },
           { groupId: "security-admins", source: "manual" },
-        ])
-      })
-    })
-
-    test("removes every directory membership when the provider grants no groups", async () => {
-      await withStorage(async (storage) => {
-        await createUser(storage)
-        await storage.groupMemberships.upsert({
-          projectId,
-          userId: "usr_1",
-          groupId: "security-admins",
-          source: "manual",
-        })
-        await storage.groupMemberships.upsert({
-          projectId,
-          userId: "usr_1",
-          groupId: "field-ops",
-          source: "directory",
-        })
-
-        await completeOidcSignInForAva(storage, [])
-
-        await expect(
-          storage.groupMemberships.listForUser({ projectId, userId: "usr_1" })
-        ).resolves.toMatchObject([{ groupId: "security-admins", source: "manual" }])
-      })
-    })
-
-    test("leaves directory memberships alone when sign-in syncs no groups", async () => {
-      await withStorage(async (storage) => {
-        await createUser(storage)
-        await storage.groupMemberships.upsert({
-          projectId,
-          userId: "usr_1",
-          groupId: "field-ops",
-          source: "directory",
-        })
+        ]
+        await expect(memberships()).resolves.toMatchObject(granted)
 
-        await completeOidcSignInForAva(storage, undefined)
+        // A sign-in that syncs no groups leaves directory memberships alone.
+        await completeOidcSignInForAva(storage, undefined, "unsynced")
+        await expect(memberships()).resolves.toMatchObject(granted)
 
-        await expect(
-          storage.groupMemberships.listForUser({ projectId, userId: "usr_1" })
-        ).resolves.toMatchObject([{ groupId: "field-ops", source: "directory" }])
+        // A provider that grants no groups removes every directory membership.
+        await completeOidcSignInForAva(storage, [], "none")
+        await expect(memberships()).resolves.toMatchObject([
+          { groupId: "commercial", source: "invitation" },
+          { groupId: "security-admins", source: "manual" },
+        ])
       })
     })
 
+    // To see this fail, return the suspended user as the previous one.
     test("suspends users and revokes active sessions immediately", async () => {
       await withStorage(async (storage) => {
-        await createUser(storage)
+        const ava = await createUser(storage)
         await storage.sessions.create({
           id: "ses_1",
           projectId,
@@ -1986,7 +2509,8 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           suspendedAt: at("2026-05-14T10:05:00.000Z"),
         })
 
-        expect(suspended.status).toBe("suspended")
+        expect(suspended.user.status).toBe("suspended")
+        expect(suspended.previousUser).toEqual(ava)
         await expect(storage.sessions.getById({ projectId, id: "ses_1" })).resolves.toMatchObject({
           revokedAt: at("2026-05-14T10:05:00.000Z"),
         })