feat(auth): cookie travels alongside Bearer + server-side sign-out

Conservative cookie-migration subset (Option A-light). The v3 gateway
sets an HttpOnly __Host-Http-r402_session cookie on successful auth
but Kychon was only persisting the JSON access_token in localStorage
and sending it as Authorization: Bearer. Two consequences:

  1. The cookie was being set but never traveled on subsequent
     requests (browsers don't send credentials cross-origin without
     `credentials: 'include'` opt-in). Defense-in-depth missing.
  2. signOut() only removed localStorage — the server-side session
     stayed valid until the access_token's natural expiry.

Now every auth.v1/* fetch and the @kychon/sdk capability call carry
`credentials: 'include'`, so the cookie travels both ways. signOut()
becomes async and POSTs /auth/v1/sign-out, killing the server-side
session before clearing the local cache. SignInBarIsland's local copy
of signOut() (which previously only cleared localStorage) now routes
through the shared @/lib/auth.signOut() so the UI sign-out button
participates in the full flow.

Bearer header kept alongside the cookie — gateway accepts either, and
during the BC window sending both is the safest combination (cookie
gives platform-side enforcement; Bearer keeps the existing JS-readable
session payload working for getRole()/isAdmin()/getSessionEmail()).

Tasks #5–#7's bigger refactor (drop localStorage entirely, convert
getRole() to async, swap to auth.whoami capability for session state)
remain deferred — they touch 8 components across the React island
graph and warrant a focused change after this cookie path is verified
on the demos.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

packages/sdk/src/index.ts

@@ -628,6 +628,10 @@ export function createKychonClient(options: KychonClientOptions) {
 
     const res = await fetchImpl(transport.endpoint, {
       method: 'POST',
+      // include cookies so the platform's HttpOnly `__Host-Http-r402_session`
+      // travels alongside the Bearer header from requestHeaders(). v3 gateway
+      // accepts either; sending both is defense-in-depth during the BC window.
+      credentials: 'include',
       headers: await requestHeaders(true),
       body: JSON.stringify(envelope),
     });

src/components/kychon/SignInBarIsland.tsx

@@ -9,7 +9,7 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from '@/components/kychon/ui';
-import { getSession } from '@/lib/auth';
+import { getSession, signOut as authSignOut } from '@/lib/auth';
 import { openAuthModal } from '@/lib/auth-modal-events';
 import { getAvailableLocales, getLocale, setLanguage, t } from '@/lib/i18n';
 
@@ -112,10 +112,14 @@ function SignInBarIsland({ showLangToggle, showThemeToggle }: SignInBarProps) {
     document.dispatchEvent(new CustomEvent('wl-locale-changed', { detail: { locale: next } }));
   }
 
-  function signOut(): void {
-    localStorage.removeItem('wl_session');
+  async function signOut(): Promise<void> {
+    // Routes through @/lib/auth.signOut so the server-side sign-out POST
+    // happens and the HttpOnly cookie is killed at the gateway, not just
+    // the localStorage cache. Fires wl-auth-changed before the redirect
+    // so any synchronous subscribers (e.g. AdminBar) update before we
+    // navigate away.
     document.dispatchEvent(new CustomEvent('wl-auth-changed'));
-    window.location.href = '/';
+    await authSignOut();
   }
 
   const showLanguage = showLangToggle && locales.length >= 2;

src/lib/api.ts

@@ -83,6 +83,7 @@ async function refreshToken(): Promise<any> {
   if (!session?.refresh_token) return null;
   const res = await fetch(`${getAPI()}/auth/v1/token?grant_type=refresh_token`, {
     method: 'POST',
+    credentials: 'include',
     headers: { 'Content-Type': 'application/json', apikey: getAnonKey() },
     body: JSON.stringify({ refresh_token: session.refresh_token }),
   });

src/lib/auth.ts

@@ -292,6 +292,7 @@ export async function signInWithGoogle(): Promise<void> {
 
   const res = await fetch(`${getAPI()}/auth/v1/oauth/google/start`, {
     method: 'POST',
+    credentials: 'include',
     headers,
     body: JSON.stringify({
       redirect_url: `${window.location.origin}/`,
@@ -333,6 +334,7 @@ export async function handleOAuthCallback(): Promise<any> {
 
   const res = await fetch(`${getAPI()}/auth/v1/token?grant_type=authorization_code`, {
     method: 'POST',
+    credentials: 'include',
     headers: { 'Content-Type': 'application/json', apikey: getAnonKey() },
     body: JSON.stringify({ code, code_verifier: verifier }),
   });
@@ -397,6 +399,7 @@ export async function handleMagicLinkCallback(): Promise<any> {
   window.history.replaceState(null, '', cleanMagicLinkCallbackUrl());
   const res = await fetch(`${getAPI()}/auth/v1/token?grant_type=magic_link`, {
     method: 'POST',
+    credentials: 'include',
     headers: publicAuthHeaders(),
     body: JSON.stringify({ token }),
   });
@@ -422,6 +425,7 @@ export async function requestGoogleConnectionLink(email: string): Promise<void>
   const redirectUrl = `${window.location.origin}${currentUrlWithParam(GOOGLE_LINK_RESUME_PARAM, '1')}`;
   const res = await fetch(`${getAPI()}/auth/v1/magic-link`, {
     method: 'POST',
+    credentials: 'include',
     headers: publicAuthHeaders(),
     body: JSON.stringify({
       email: normalizedEmail,
@@ -441,6 +445,7 @@ export async function requestGoogleConnectionLink(email: string): Promise<void>
 export async function signUp(email: string, password: string): Promise<any> {
   const res = await fetch(`${getAPI()}/auth/v1/signup`, {
     method: 'POST',
+    credentials: 'include',
     headers: { 'Content-Type': 'application/json', apikey: getAnonKey() },
     body: JSON.stringify({ email, password }),
   });
@@ -454,6 +459,7 @@ export async function signUp(email: string, password: string): Promise<any> {
 export async function signIn(email: string, password: string): Promise<any> {
   const res = await fetch(`${getAPI()}/auth/v1/token?grant_type=password`, {
     method: 'POST',
+    credentials: 'include',
     headers: { 'Content-Type': 'application/json', apikey: getAnonKey() },
     body: JSON.stringify({ email, password }),
   });
@@ -472,6 +478,7 @@ export async function setPassword(newPassword: string, currentPassword?: string)
 
   const res = await fetch(`${getAPI()}/auth/v1/user/password`, {
     method: 'PUT',
+    credentials: 'include',
     headers: {
       'Content-Type': 'application/json',
       apikey: getAnonKey(),
@@ -499,6 +506,7 @@ export async function getCurrentUser(appOrigin = window.location.origin): Promis
   const url = new URL(`${getAPI()}/auth/v1/user`);
   if (appOrigin) url.searchParams.set('app_origin', appOrigin);
   const res = await fetch(url.toString(), {
+    credentials: 'include',
     headers: {
       apikey: getAnonKey(),
       Authorization: `Bearer ${requireAccessToken()}`,
@@ -542,6 +550,7 @@ export function passkeysSupported(): boolean {
 
 export async function listPasskeys(): Promise<any[]> {
   const res = await fetch(`${getAPI()}/auth/v1/passkeys`, {
+    credentials: 'include',
     headers: {
       apikey: getAnonKey(),
       Authorization: `Bearer ${requireAccessToken()}`,
@@ -559,6 +568,7 @@ export async function registerPasskey(label = 'Kychon admin passkey'): Promise<a
   const accessToken = requireAccessToken();
   const optionsRes = await fetch(`${getAPI()}/auth/v1/passkeys/register/options`, {
     method: 'POST',
+    credentials: 'include',
     headers: {
       'Content-Type': 'application/json',
       apikey: getAnonKey(),
@@ -578,6 +588,7 @@ export async function registerPasskey(label = 'Kychon admin passkey'): Promise<a
 
   const verifyRes = await fetch(`${getAPI()}/auth/v1/passkeys/register/verify`, {
     method: 'POST',
+    credentials: 'include',
     headers: {
       'Content-Type': 'application/json',
       apikey: getAnonKey(),
@@ -602,6 +613,7 @@ export async function signInWithPasskey(email?: string): Promise<any> {
   }
   const optionsRes = await fetch(`${getAPI()}/auth/v1/passkeys/login/options`, {
     method: 'POST',
+    credentials: 'include',
     headers: publicAuthHeaders(),
     body: JSON.stringify({
       app_origin: window.location.origin,
@@ -620,6 +632,7 @@ export async function signInWithPasskey(email?: string): Promise<any> {
 
   const verifyRes = await fetch(`${getAPI()}/auth/v1/passkeys/login/verify`, {
     method: 'POST',
+    credentials: 'include',
     headers: publicAuthHeaders(),
     body: JSON.stringify({
       challenge_id: optionsBody?.challenge_id,
@@ -697,7 +710,27 @@ function credentialToJSON(credential: PublicKeyCredential): any {
   return json;
 }
 
-export function signOut(): void {
+export async function signOut(): Promise<void> {
+  // Server-side sign-out so the HttpOnly cookie is killed at the gateway,
+  // not just the localStorage cache. We send credentials so the gateway
+  // can identify the session to invalidate. Best-effort: even if the POST
+  // fails we still clear the local cache and redirect — a stale server
+  // session is worse than a stale client cache, but better than neither.
+  try {
+    const session = getSession();
+    const headers: Record<string, string> = { apikey: getAnonKey() };
+    if (typeof session?.access_token === 'string' && session.access_token) {
+      headers.Authorization = `Bearer ${session.access_token}`;
+    }
+    await fetch(`${getAPI()}/auth/v1/sign-out`, {
+      method: 'POST',
+      credentials: 'include',
+      headers,
+    });
+  } catch {
+    // Network failure during sign-out is not user-actionable. Continue to
+    // clear local state so the UI reflects signed-out.
+  }
   localStorage.removeItem('wl_session');
   window.location.href = '/';
 }

tests/unit/auth.test.js

@@ -479,13 +479,18 @@ describe('auth.js', () => {
   });
 
   describe('signOut', () => {
-    it('clears session', () => {
+    it('clears session and POSTs server-side sign-out', async () => {
       localStorage.setItem('wl_session', JSON.stringify({ access_token: 'tok' }));
+      global.fetch.mockResolvedValueOnce({ ok: true, json: async () => ({}) });
       // Mock window.location
       delete global.window.location;
       global.window.location = { href: '' };
-      auth.signOut();
+      await auth.signOut();
       expect(localStorage.getItem('wl_session')).toBeNull();
+      const [url, init] = global.fetch.mock.calls[0] ?? [];
+      expect(String(url)).toContain('/auth/v1/sign-out');
+      expect(init?.method).toBe('POST');
+      expect(init?.credentials).toBe('include');
     });
   });
 });