Authentication

// Token mode (default) — cross-origin SPA
createAuthClient(baseUrl);

// Cookie mode — same-origin / SSR
createAuthClient(baseUrl, { strategy: { kind: "cookie" } });

Sign In →  Server returns { sessionToken, token (JWT), user }
           │
           ├── JWT (5min) → stored in memory only
           ├── sessionToken (7d) → stored in localStorage (default)
           └── user → stored in localStorage (optimistic UI)

Page reload → sessionToken from localStorage
           → POST /api/auth/token → new JWT
           → UI shows user immediately (from localStorage cache)

JWT expires → protected queries/mutations refresh first using sessionToken (no user action needed)

createAuthClient(baseUrl, {
    strategy: { kind: "token", sessionTokenStorage: "memory" },
});

Sign In →  POST /api/auth/sign-in/email
           → Server sets better-auth.session_token (HttpOnly cookie)
           → Client stores user in memory for optimistic UI

Protected API → fetch(..., { credentials: "include" })
              → Browser attaches cookie; server validates session

Page reload → Cookie sent automatically; GET /api/auth/me hydrates user

// gencow/auth.ts
export default defineAuth({
    oauth: {
        // Token-only OAuth (default) — cross-origin SPAs
        allowedReturnModes: ["token"],

        // Cookie-only OAuth — same-origin / HttpOnly session required
        // allowedReturnModes: ["cookie"],

        // Both — only when the same backend intentionally serves both client styles
        // allowedReturnModes: ["token", "cookie"],
    },
});

// src/lib/auth.ts
import { createAuthClient } from "@gencow/client";

const baseUrl = import.meta.env.VITE_API_URL ?? "http://localhost:5456";

// Pass the same backend origin used by queries, mutations, and realtime tickets.
export const auth = createAuthClient(baseUrl);
export const { signIn, signUp, signOut } = auth;

// src/lib/apiClient.ts
import { createGencowClient } from "@gencow/client";
import { api } from "../gencow/api";
import { auth } from "./auth";

const baseUrl = import.meta.env.VITE_API_URL ?? "http://localhost:5456";

export const apiClient = createGencowClient({ api, baseUrl, auth });

// src/main.tsx
import { GencowProvider } from "@gencow/react";
import { apiClient } from "./lib/apiClient";

function AppWrapper({ children }: { children: React.ReactNode }) {
    return (
        <GencowProvider apiClient={apiClient}>
            {children}
        </GencowProvider>
    );
}

import { signIn, signUp, signOut } from "./lib/auth";
import { useAuth } from "@gencow/react";

function AuthComponent() {
    const { user, isAuthenticated } = useAuth();

    if (!isAuthenticated) {
        return <LoginForm />;
    }

    return (
        <div>
            <p>Welcome, {user?.name || user?.email}</p>
            <button onClick={() => signOut()}>Sign Out</button>
        </div>
    );
}

try {
    const user = await signUp("[email protected]", "password123", "John Doe");
    // user = { id, email, name }
    // Session is automatically established
} catch (e) {
    console.error(e.message); // "Email already registered" etc.
}

try {
    const user = await signIn("[email protected]", "password123");
    // user = { id, email, name }
    // Token mode: JWT + sessionToken stored client-side
    // Cookie mode: HttpOnly session cookie set by the server
} catch (e) {
    console.error(e.message); // "Invalid credentials" etc.
}

await signOut();
// Token mode: clears JWT, sessionToken, and cached user from memory/storage
// Cookie mode: clears the HttpOnly session cookie server-side

gencow add sso

import { GoogleSignInButton } from "./auth/google-sign-in-button";

export function LoginPage() {
    return <GoogleSignInButton />;
}

Authorized JavaScript origin:
https://<app>.<domain>

Authorized redirect URI:
https://<app>.<domain>/api/auth/callback/google

// src/auth/callback.tsx
import { useEffect, useState } from "react";
import { auth } from "../lib/auth";

export function AuthCallbackPage() {
    const [error, setError] = useState<string | null>(null);

    useEffect(() => {
        const params = new URLSearchParams(window.location.search);
        const code = params.get("code") ?? undefined;
        const oauthSuccess = params.get("oauth") === "success";
        const oauthError = params.get("error");

        if (oauthError) {
            setError(oauthError);
            return;
        }

        if (!code && !oauthSuccess) {
            setError("Missing OAuth callback result");
            return;
        }

        auth.completeSocialSignIn(code)
            .then(() => {
                window.history.replaceState({}, "", "/");
                window.location.assign("/");
            })
            .catch((e) => {
                setError(e instanceof Error ? e.message : String(e));
            });
    }, []);

    if (error) return <p>{error}</p>;
    return <p>Completing sign in...</p>;
}

import { auth } from "../lib/auth";

export function GoogleSignInButton() {
    return (
        <button
            type="button"
            onClick={() => auth.signInSocial("google", {
                callbackURL: `${window.location.origin}/auth/callback`,
            })}
        >
            Continue with Google
        </button>
    );
}

/** @type {import("@gencow/core").GencowConfig} */
export default {
    frontendOrigins: ["https://my-frontend.vercel.app"],
};

// src/lib/auth-client.ts
import { createAuthClient } from "@gencow/client";

export const auth = createAuthClient({
    baseURL: process.env.NEXT_PUBLIC_GENCOW_URL,
    authBridge: {
        basePath: "/api/auth",
        oauthCallbackPath: "/auth/callback",
    },
});

// app/api/auth/[...action]/route.ts
import { createGencowAuthBridgeHandlers } from "@gencow/client";
import { bridgeSessionAdapter } from "@/lib/session";

const handlers = createGencowAuthBridgeHandlers({
    gencowBaseUrl: process.env.NEXT_PUBLIC_GENCOW_URL!,
    session: bridgeSessionAdapter,
});

export async function POST(req: Request) {
    return handlers.handle(req);
}

import { createServerGencowClient } from "@gencow/client";
import { getGencowServerAuth, useServerQuery } from "@gencow/client/next";
import { api } from "@/lib/api";
import { getBridgeSession } from "@/lib/session";

const auth = await getGencowServerAuth(getBridgeSession);
if (!auth) redirect("/login");

const profile = await useServerQuery(api.users.profile, undefined, {
    baseUrl: process.env.NEXT_PUBLIC_GENCOW_URL!,
    auth,
});

const serverClient = createServerGencowClient({
    api,
    baseUrl: process.env.NEXT_PUBLIC_GENCOW_URL!,
    auth,
});
await serverClient.call.mutate(api.users.updateDisplayName, { displayName });

import { useAuth } from "@gencow/react";

const { token, user, isAuthenticated } = useAuth();

import { defineAuth } from "@gencow/core";

export default defineAuth({
    user: {
        additionalFields: {
            role: { type: "text", default: "user" },
        },
    },
    // Add better-auth plugins/options:
    // betterAuth: (defaults) => ({
    //     ...defaults,
    //     plugins: [
    //         ...((defaults.plugins as unknown[]) ?? []),
    //         // better-auth plugin instances
    //     ],
    // }),
    // Add email verification:
    // emailVerification: {
    //     sendVerificationEmail: async ({ email, url }) => {
    //         // Send email using your preferred provider
    //     },
    // },
});

// gencow/auth.ts
export default defineAuth({
    user: {
        additionalFields: {
            role: { type: "text", default: "user" },
        },
    },
});

// gencow/schema-auth.ts
export * from "./generated/schema-auth.gen";

gencow codegen
gencow db:generate
gencow db:push --local

// gencow.config.js
/** @type {import('@gencow/core').GencowConfig} */
export default {
  codegen: {
    authSchema: false,
  },
};

// ❌ Don't create custom auth routes
fetch("/auth/register", { ... })
fetch("/api/users/login", { ... })

// ❌ Don't manage JWT tokens manually
localStorage.setItem("token", jwt)
headers: { Authorization: `Bearer ${myToken}` }

// ❌ Don't hand-roll cookie mode fetches
fetch("/api/auth/sign-in/email", { credentials: "include" })

// ✅ Use createAuthClient() from @gencow/client — it handles everything
import { createAuthClient } from "@gencow/client";

export const auth = createAuthClient(baseUrl, { strategy: { kind: "cookie" } });
export const { signIn, signUp, signOut } = auth;
await signIn("[email protected]", "password123");
// useAuth() inside <GencowProvider apiClient={apiClient}>