@playcademy/better-auth 0.0.1-alpha.1 → 0.0.2

package/dist/client.d.ts

@@ -19,48 +19,122 @@
  * ```
  */
 import { playcademy as playcademyServerPlugin } from './server';
+/**
+ * Configuration options for the Playcademy Better Auth client plugin
+ *
+ * Configures how the client handles platform authentication and Safari
+ * Storage Access API integration.
+ */
 export interface PlaycademyClientOptions {
     /**
-     * Automatically show storage access prompt for Safari users
-     *
-     * When true (default), Safari users in iframes will see an automatic
-     * prompt to grant storage access (required for cookies in Safari).
-     *
-     * Set to false if you want to handle Safari storage access yourself.
+     * Safari browser configuration.
      *
-     * @default true
+     * Controls how the plugin handles Safari's Storage Access API requirements
+     * for cross-origin cookies in iframes.
      */
     safari?: {
+        /**
+         * Automatically show storage access prompt for Safari users.
+         *
+         * When `true` (default), Safari users running the game in an iframe
+         * (platform mode) will automatically see a prompt to grant cookie
+         * access. This is required for authentication to work in Safari iframes.
+         *
+         * Set to `false` if you want to handle Safari storage access manually
+         * or have a custom flow.
+         *
+         * **Why this is needed**: Safari blocks third-party cookies in iframes
+         * by default. The Storage Access API allows users to explicitly grant
+         * cookie access after a user interaction.
+         *
+         * @default true
+         * @example
+         * ```ts
+         * {
+         *   safari: {
+         *     autoPrompt: true // Show automatic prompt (recommended)
+         *   }
+         * }
+         * ```
+         *
+         * @example
+         * ```ts
+         * {
+         *   safari: {
+         *     autoPrompt: false // Handle Safari auth manually
+         *   }
+         * }
+         * ```
+         */
         autoPrompt?: boolean;
     };
 }
 /**
  * Playcademy client plugin for Better Auth
  *
- * Automatically handles:
- * - Platform vs standalone mode detection
- * - Token exchange for platform mode
- * - Safari Storage Access API (auto-prompt)
+ * Enables seamless authentication for Playcademy games that run both:
+ * - In the Playcademy platform (iframe with JWT token exchange)
+ * - As standalone games (standard Better Auth with cookies)
+ *
+ * **Key Features**:
+ * - Automatic platform vs standalone mode detection
+ * - JWT token exchange for platform authentication
+ * - Safari Storage Access API handling (automatic prompt)
+ * - Cookie-based auth with CHIPS support for Chrome/Edge
+ * - Zero configuration required
+ *
+ * **How it works**:
+ * 1. Platform mode: Exchanges platform JWT for Better Auth session
+ * 2. Standalone mode: Uses standard Better Auth providers (email/OAuth)
+ * 3. Safari: Automatically requests storage access for iframe cookies
+ *
+ * @param options - Configuration options (optional)
+ * @returns Better Auth client plugin
  *
  * @example
  * ```typescript
- * // Default: Auto-handles everything including Safari
+ * // Recommended: Use defaults (handles everything automatically)
+ * import { createAuthClient } from 'better-auth/react'
+ * import { playcademy } from '@playcademy/better-auth/client'
+ *
  * const auth = createAuthClient({
+ *   baseURL: 'http://localhost:8788',
  *   plugins: [playcademy()]
  * })
+ *
+ * // Access auth in your components
+ * export const { useSession } = auth
  * ```
  *
  * @example
  * ```typescript
- * // Custom: Disable auto Safari prompt
+ * // Custom: Disable Safari auto-prompt
  * const auth = createAuthClient({
+ *   baseURL: 'http://localhost:8788',
  *   plugins: [
  *     playcademy({
- *       safari: { autoPrompt: false }
+ *       safari: {
+ *         autoPrompt: false // Handle Safari manually
+ *       }
  *     })
  *   ]
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Use session in React component
+ * import { useSession } from './lib/auth'
+ *
+ * function App() {
+ *   const { data: session, isPending } = useSession()
+ *
+ *   if (isPending) return <div>Loading...</div>
+ *   if (!session) return <div>Not logged in</div>
+ *
+ *   return <div>Welcome, {session.user.name}!</div>
+ * }
+ * ```
  */
 export declare function playcademy(options?: PlaycademyClientOptions): {
     id: "playcademy-client";

package/dist/client.js

@@ -118,12 +118,24 @@ function playcademyExchangePlugin(_opts) {
         if (!canProceed) {
           return;
         }
-        await fetch("/api/auth/playcademy", {
-          method: "POST",
-          headers: { Authorization: `Bearer ${token}` },
-          credentials: "include"
-        });
-        exchangeComplete = true;
+        try {
+          const headers = { Authorization: `Bearer ${token}` };
+          if (isPlatformMode()) {
+            headers["X-Playcademy-Mode"] = "platform";
+          }
+          const response = await fetch("/api/auth/playcademy", {
+            method: "POST",
+            headers,
+            credentials: "include"
+          });
+          if (response.status === 204) {
+            exchangeComplete = true;
+          } else if (response.status !== 200 && response.status !== 500) {
+            console.warn(`[Playcademy Auth] Unexpected response status: ${response.status}`);
+          }
+        } catch (error) {
+          console.warn("[Playcademy Auth] Network error during token exchange:", error);
+        }
       })();
       await exchangePromise;
       return { url, options };

package/dist/server.d.ts

@@ -1,30 +1,144 @@
 /**
- * Playcademy plugin for Better Auth
+ * Playcademy Platform Authentication Plugin (Server)
  *
- * This plugin provides:
- * - Platform user schema field (playcademyUserId)
- * - Token exchange endpoint (POST /api/auth/playcademy)
+ * Enables seamless authentication for Playcademy games that run both:
+ * - In the Playcademy platform (iframe with JWT token exchange)
+ * - As standalone games (standard Better Auth with cookies)
+ *
+ * **Key Features**:
+ * - Platform JWT token exchange endpoint (`POST /api/auth/playcademy`)
  * - Automatic account linking between platform and standalone modes
- * - Cross-site cookie support with CHIPS
+ * - Cross-site cookie support with CHIPS (Partitioned cookies)
+ * - Schema extension: adds `playcademyUserId` to user model
+ * - Safari Storage Access API compatibility
+ *
+ * **How it works**:
+ *
+ * 1. **Platform Mode (iframe)**:
+ *    - Game receives JWT token from Playcademy platform
+ *    - Client exchanges token via `/api/auth/playcademy` endpoint
+ *    - Server verifies token with platform API (uses PLAYCADEMY_BASE_URL env var)
+ *    - Creates or links Better Auth user by `playcademyUserId`
+ *    - Returns session cookie with CHIPS support
+ *
+ * 2. **Standalone Mode**:
+ *    - Users authenticate via Better Auth providers (email, OAuth, etc.)
+ *    - If they later access via platform, accounts are linked by `playcademyUserId`
+ *
+ * 3. **Account Linking**:
+ *    - Platform users get `playcademyUserId` set automatically
+ *    - If a user exists with that `playcademyUserId`, sessions merge
+ *    - Enables seamless switching between platform and standalone
+ *
+ * **Development/Testing**:
+ *
+ * To test deployed games against a local platform API, set the `PLAYCADEMY_AUTH_API_URL`
+ * environment variable to override the platform URL (e.g., using a tunnel service):
+ *
+ * ```bash
+ * PLAYCADEMY_AUTH_API_URL=https://your-tunnel.dev
+ * ```
+ *
+ * **Cookie Configuration**:
+ *
+ * For cross-origin iframe authentication to work, you MUST configure cookies:
+ *
+ * ```typescript
+ * advanced: {
+ *   defaultCookieAttributes: {
+ *     sameSite: 'none',    // Allow cross-site cookies
+ *     secure: true,        // HTTPS only (required for sameSite: none)
+ *     path: '/',           // Available across entire site
+ *     partitioned: true,   // CHIPS for Chrome/Edge
+ *   }
+ * }
+ * ```
+ *
+ * **Safari Compatibility**:
+ *
+ * Safari doesn't support CHIPS. The client plugin automatically handles
+ * Safari Storage Access API to request cookie permission from users.
+ *
+ * @returns Better Auth server plugin
  *
  * @example
  * ```typescript
+ * // Basic setup
  * import { betterAuth } from 'better-auth'
+ * import { drizzleAdapter } from 'better-auth/adapters/drizzle'
  * import { playcademy } from '@playcademy/better-auth/server'
+ * import { db } from './db'
  *
  * export const auth = betterAuth({
  *   database: drizzleAdapter(db, { provider: 'sqlite' }),
+ *
+ *   // Required: Platform integration
  *   plugins: [playcademy()],
+ *
+ *   // Required: Cross-site cookie support
  *   advanced: {
  *     defaultCookieAttributes: {
  *       sameSite: 'none',
  *       secure: true,
  *       path: '/',
  *       partitioned: true, // CHIPS for Chrome/Edge
- *     },
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With email/password and OAuth
+ * export const auth = betterAuth({
+ *   database: drizzleAdapter(db, { provider: 'sqlite' }),
+ *
+ *   // Platform auth (always included)
+ *   plugins: [playcademy()],
+ *
+ *   // Optional: Email/password for standalone
+ *   emailAndPassword: {
+ *     enabled: true
+ *   },
+ *
+ *   // Optional: OAuth for standalone
+ *   socialProviders: {
+ *     github: {
+ *       clientId: process.env.GITHUB_CLIENT_ID!,
+ *       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     }
  *   },
+ *
+ *   advanced: {
+ *     defaultCookieAttributes: {
+ *       sameSite: 'none',
+ *       secure: true,
+ *       path: '/',
+ *       partitioned: true,
+ *     }
+ *   }
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in API route handler
+ * import { Context } from 'hono'
+ * import { auth } from './lib/auth'
+ *
+ * export async function GET(c: Context) {
+ *   const session = await auth.api.getSession({
+ *     headers: c.req.raw.headers
+ *   })
+ *
+ *   if (!session) {
+ *     return c.json({ error: 'Unauthorized' }, 401)
+ *   }
+ *
+ *   // session.user.playcademyUserId available if from platform
+ *   return c.json({ user: session.user })
+ * }
+ * ```
  */
 export declare const playcademy: () => {
     id: "playcademy";

package/dist/server.js

@@ -20473,7 +20473,6 @@ Please set the PLAYCADEMY_BASE_URL environment variable`);
 // src/server.ts
 var DEFAULT_SESSION_MAX_AGE = 60 * 60 * 24 * 7;
 var DEFAULT_COOKIE_PATH = "/";
-var DEV_TUNNEL_URL = "https://hbauer.playcademy.dev";
 function extractGameToken(authHeader) {
   if (!authHeader?.startsWith("Bearer ")) {
     throw new Error("Missing or invalid Authorization header");
@@ -20602,50 +20601,66 @@ var playcademy = () => {
       }, async (ctx) => {
         const authHeader = ctx.request?.headers.get("authorization");
         const gameToken = extractGameToken(authHeader ?? "");
-        const isLocalDev = ctx.request?.url.includes("localhost");
-        const platformApiUrl = isLocalDev ? undefined : DEV_TUNNEL_URL;
+        const authApiUrl = process.env.PLAYCADEMY_AUTH_API_URL || undefined;
         let verified = null;
         try {
-          verified = await verifyGameToken(gameToken, {
-            baseUrl: platformApiUrl
+          verified = await verifyGameToken(gameToken, { baseUrl: authApiUrl });
+        } catch (error4) {
+          const errorMessage = error4 instanceof Error ? error4.message : String(error4);
+          const platformMode = ctx.request?.headers.get("x-playcademy-mode");
+          if (platformMode === "platform") {
+            console.error("[Playcademy Auth] Token verification failed:", {
+              error: errorMessage,
+              hasAuthApiOverride: !!authApiUrl
+            });
+          }
+          return new Response(JSON.stringify({ ok: false, code: "invalid_token" }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" }
           });
-        } catch {
-          return new Response(null, { status: 204 });
-        }
-        const user = await findOrCreateUser(ctx.context.adapter, verified.user);
-        if (!user) {
-          throw new Error("Failed to find or create user");
         }
-        const cookieName = ctx.context.authCookies.sessionToken.name;
-        const cookieHeader = ctx.request?.headers.get("cookie") ?? null;
-        const ctxSecret = ctx.context.secret;
-        const existingSession = await readSignedSessionCookie(cookieHeader, cookieName, ctxSecret);
-        if (existingSession) {
-          const isValid = await hasValidSession(ctx.context.adapter, existingSession.token, user.id);
-          if (isValid) {
-            return new Response(null, { status: 204 });
+        try {
+          const user = await findOrCreateUser(ctx.context.adapter, verified.user);
+          if (!user) {
+            throw new Error("Failed to find or create user");
           }
-        }
-        const session = await ctx.context.internalAdapter.createSession(user.id, ctx);
-        if (!session) {
-          throw new Error("Failed to create session");
-        }
-        const cookieOpts = ctx.context.authCookies.sessionToken.options;
-        const setCookieValue = await buildCrossSiteCookie({
-          cookieName,
-          sessionToken: session.token,
-          secret: ctxSecret,
-          maxAge: cookieOpts.maxAge ?? DEFAULT_SESSION_MAX_AGE,
-          path: cookieOpts.path ?? DEFAULT_COOKIE_PATH,
-          userAgent: ctx.request?.headers.get("user-agent") ?? null
-        });
-        return new Response(null, {
-          status: 200,
-          headers: {
-            "Set-Cookie": setCookieValue,
-            "Content-Type": "application/json"
+          const cookieName = ctx.context.authCookies.sessionToken.name;
+          const cookieHeader = ctx.request?.headers.get("cookie") ?? null;
+          const ctxSecret = ctx.context.secret;
+          const existingSession = await readSignedSessionCookie(cookieHeader, cookieName, ctxSecret);
+          if (existingSession) {
+            const isValid = await hasValidSession(ctx.context.adapter, existingSession.token, user.id);
+            if (isValid) {
+              return new Response(null, { status: 204 });
+            }
           }
-        });
+          const session = await ctx.context.internalAdapter.createSession(user.id, ctx);
+          if (!session) {
+            throw new Error("Failed to create session");
+          }
+          const cookieOpts = ctx.context.authCookies.sessionToken.options;
+          const setCookieValue = await buildCrossSiteCookie({
+            cookieName,
+            sessionToken: session.token,
+            secret: ctxSecret,
+            maxAge: cookieOpts.maxAge ?? DEFAULT_SESSION_MAX_AGE,
+            path: cookieOpts.path ?? DEFAULT_COOKIE_PATH,
+            userAgent: ctx.request?.headers.get("user-agent") ?? null
+          });
+          return new Response(null, {
+            status: 204,
+            headers: {
+              "Set-Cookie": setCookieValue
+            }
+          });
+        } catch (error4) {
+          const errorMessage = error4 instanceof Error ? error4.message : String(error4);
+          console.error("[Playcademy Auth] Internal error during token exchange/session setup:", { error: errorMessage });
+          return new Response(JSON.stringify({ ok: false, code: "internal_error" }), {
+            status: 500,
+            headers: { "Content-Type": "application/json" }
+          });
+        }
       })
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/better-auth",
-    "version": "0.0.1-alpha.1",
+    "version": "0.0.2",
     "type": "module",
     "exports": {
         "./server": {
@@ -28,7 +28,7 @@
     },
     "devDependencies": {
         "@inquirer/prompts": "^7.9.0",
-        "@playcademy/sdk": "0.1.13",
+        "@playcademy/sdk": "0.1.18",
         "@playcademy/utils": "0.0.1",
         "@types/bun": "latest",
         "typescript": "^5.7.2"