feat: add Convex auth recovery

.changeset/brave-cats-recover.md

@@ -0,0 +1,7 @@
+---
+"kitcn": patch
+---
+
+## Features
+
+- Add provider-owned Convex authentication recovery after transient token failures.

packages/kitcn/skills/kitcn/references/features/auth.md

@@ -358,6 +358,7 @@ All from `kitcn/react`:
 | `useMaybeAuth()` | `boolean` | Has token (optimistic, may not be verified) |
 | `useIsAuth()` | `boolean` | Server-verified authentication |
 | `useAuthGuard()` | `() => boolean` | Guard mutations, returns true if blocked |
+| `useConvexAuthRecovery()` | `{ recover, status, error }` | Rebind Convex auth after a transient token failure |
 
 ### useAuthGuard
 
@@ -409,6 +410,28 @@ import { ConvexProviderWithAuth } from 'kitcn/react';
 <ConvexProviderWithAuth client={convex} useAuth={useAuthFromConvexDev}>
 ```
 
+### Convex Auth Recovery
+
+Use recovery only when the outer auth provider remains authenticated but
+Convex entered an unauthenticated state after a transient token refresh
+failure:
+
+```tsx
+import { useConvexAuthRecovery } from 'kitcn/react';
+
+const { error, recover, status } = useConvexAuthRecovery();
+await recover();
+```
+
+`recover()` replaces the provider-owned auth binding and resolves after Convex
+confirms authentication. Concurrent calls share one promise. The default
+timeout is 10 seconds; override it with `recover({ timeoutMs })`.
+
+Failures are `ConvexAuthRecoveryError` values with code
+`AUTH_PROVIDER_LOADING`, `AUTH_PROVIDER_UNAUTHENTICATED`,
+`AUTH_RECOVERY_CANCELLED`, `AUTH_RECOVERY_FAILED`, or
+`AUTH_RECOVERY_TIMEOUT`. Never recover an intentional sign-out.
+
 ---
 
 ## Auth Triggers

packages/kitcn/src/auth-client/convex-auth-provider.test.tsx

@@ -1,9 +1,10 @@
-import { act, render, renderHook } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
 import type { ReactNode } from 'react';
 import {
   decodeJwtExp,
   useAuth,
   useAuthStore,
+  useConvexAuthRecovery,
   useFetchAccessToken,
 } from '../react/auth-store';
 import { ConvexAuthProvider } from './convex-auth-provider';
@@ -31,6 +32,92 @@ describe('ConvexAuthProvider', () => {
     }
   });
 
+  test('recovers Better Auth after a transient token refresh failure', async () => {
+    const bindings: Array<{
+      fetchToken: (args: {
+        forceRefreshToken: boolean;
+      }) => Promise<string | null>;
+      onChange: (isAuthenticated: boolean) => void;
+    }> = [];
+    const client = {
+      clearAuth: mock(() => {}),
+      setAuth: mock(
+        (
+          fetchToken: (args: {
+            forceRefreshToken: boolean;
+          }) => Promise<string | null>,
+          onChange: (isAuthenticated: boolean) => void
+        ) => {
+          bindings.push({ fetchToken, onChange });
+        }
+      ),
+    };
+    const recoveredToken = makeJwt(7200);
+    const token = mock()
+      .mockResolvedValueOnce({ data: {} })
+      .mockResolvedValueOnce({ data: { token: recoveredToken } });
+    const authClient = {
+      useSession: () => ({
+        data: { session: { id: 'session-1' } },
+        isPending: false,
+      }),
+      convex: { token },
+      getSession: async () => null,
+      updateSession: () => {},
+      crossDomain: { oneTimeToken: { verify: async () => ({ data: {} }) } },
+    };
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <ConvexAuthProvider authClient={authClient as any} client={client as any}>
+        {children}
+      </ConvexAuthProvider>
+    );
+
+    let recovery: ReturnType<typeof useConvexAuthRecovery> | undefined;
+    expect(() => {
+      renderHook(
+        () => {
+          recovery = useConvexAuthRecovery();
+        },
+        { wrapper }
+      );
+    }).not.toThrow();
+
+    await waitFor(() => {
+      expect(bindings).toHaveLength(1);
+    });
+    let failedToken: string | null = null;
+    await act(async () => {
+      failedToken = await bindings[0]!.fetchToken({
+        forceRefreshToken: true,
+      });
+    });
+    expect(failedToken).toBeNull();
+    act(() => {
+      bindings[0]!.onChange(false);
+    });
+
+    let recovered!: Promise<void>;
+    act(() => {
+      recovered = recovery!.recover({ timeoutMs: 1_000 });
+    });
+    await waitFor(() => {
+      expect(bindings).toHaveLength(2);
+    });
+    let freshToken: string | null = null;
+    await act(async () => {
+      freshToken = await bindings[1]!.fetchToken({
+        forceRefreshToken: false,
+      });
+    });
+    expect(freshToken).toBe(recoveredToken);
+    act(() => {
+      bindings[1]!.onChange(true);
+    });
+
+    await expect(recovered).resolves.toBeUndefined();
+    expect(token).toHaveBeenCalledTimes(2);
+  });
+
   test('syncs ConvexQueryClient with the auth store before children render', () => {
     const client = {
       setAuth: () => {},

packages/kitcn/src/auth-client/convex-auth-provider.tsx

@@ -6,7 +6,7 @@
 
 import type { AuthTokenFetcher } from 'convex/browser';
 import type { ConvexReactClient } from 'convex/react';
-import { ConvexProviderWithAuth, useConvexAuth } from 'convex/react';
+import { useConvexAuth } from 'convex/react';
 import type { ReactNode } from 'react';
 import { useCallback, useEffect, useMemo, useRef } from 'react';
 
@@ -21,6 +21,7 @@ import {
   AUTH_SESSION_SYNC_GRACE_MS,
   AuthProvider,
   type AuthStore,
+  ConvexProviderWithAuth,
   decodeJwtExp,
   FetchAccessTokenContext,
   isSessionSyncGraceActive,