@playcademy/better-auth 0.0.1-alpha.1

package/README.md

@@ -0,0 +1,57 @@
+# @playcademy/better-auth
+
+Better Auth integration for Playcademy games with automatic platform/standalone mode detection and Safari Storage Access API support.
+
+## Installation
+
+```bash
+bun add @playcademy/better-auth better-auth
+```
+
+## Usage
+
+### Server
+
+```typescript
+import { betterAuth } from 'better-auth'
+
+import { playcademy } from '@playcademy/better-auth/server'
+
+export const auth = betterAuth({
+    database: drizzleAdapter(db, { provider: 'sqlite' }),
+    plugins: [playcademy()],
+    advanced: {
+        defaultCookieAttributes: {
+            sameSite: 'none',
+            secure: true,
+            path: '/',
+            partitioned: true, // CHIPS for Chrome/Edge
+        },
+    },
+})
+```
+
+### Client
+
+```typescript
+import { createAuthClient } from 'better-auth/react'
+
+import { playcademy } from '@playcademy/better-auth/client'
+
+const auth = createAuthClient({
+    plugins: [playcademy()],
+})
+```
+
+## Features
+
+- **Automatic mode detection**: Seamlessly switches between platform (iframe) and standalone modes
+- **Cookie-based auth**: Uses HttpOnly cookies for security
+- **CHIPS support**: Partitioned cookies for Chrome/Edge in iframes
+- **Safari support**: Automatic Storage Access API prompts for Safari users
+- **Zero configuration**: Works out of the box with sensible defaults
+
+## Requirements
+
+- **HTTPS required**: Both platform and game must use HTTPS (Safari requirement)
+- **Storage Access API**: Safari users see a one-time prompt to allow cookies in iframes

package/dist/client.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Playcademy Auth Client Plugin
+ *
+ * Handles platform/standalone auth automatically:
+ * - Platform mode: Uses cookies with automatic Storage Access API for Safari
+ * - Standalone mode: Uses cookies
+ *
+ * Safari in iframes requires Storage Access API - this plugin handles it automatically!
+ *
+ * @example
+ * ```typescript
+ * import { createAuthClient } from 'better-auth/react'
+ * import { playcademy } from '@playcademy/better-auth/client'
+ *
+ * // That's it! Safari Storage Access API handled automatically
+ * const auth = createAuthClient({
+ *   plugins: [playcademy()]
+ * })
+ * ```
+ */
+import { playcademy as playcademyServerPlugin } from './server';
+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.
+     *
+     * @default true
+     */
+    safari?: {
+        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)
+ *
+ * @example
+ * ```typescript
+ * // Default: Auto-handles everything including Safari
+ * const auth = createAuthClient({
+ *   plugins: [playcademy()]
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom: Disable auto Safari prompt
+ * const auth = createAuthClient({
+ *   plugins: [
+ *     playcademy({
+ *       safari: { autoPrompt: false }
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+export declare function playcademy(options?: PlaycademyClientOptions): {
+    id: "playcademy-client";
+    $InferServerPlugin: ReturnType<typeof playcademyServerPlugin>;
+    fetchPlugins: import("@better-fetch/fetch").BetterFetchPlugin[];
+};

package/dist/client.js

@@ -0,0 +1,278 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/utils.ts
+function isPlatformMode() {
+  if (typeof window === "undefined")
+    return false;
+  if (window.self === window.top)
+    return false;
+  return true;
+}
+function isSafari() {
+  if (typeof window === "undefined")
+    return false;
+  const ua = navigator.userAgent;
+  return ua.includes("Safari") && !ua.includes("Chrome") && !ua.includes("Chromium");
+}
+function getPlatformToken() {
+  if (typeof window === "undefined")
+    return null;
+  try {
+    return window.PLAYCADEMY?.token || null;
+  } catch {
+    return null;
+  }
+}
+function hasStorageAccessAPI() {
+  return typeof document !== "undefined" && "hasStorageAccess" in document;
+}
+async function needsStorageAccess() {
+  if (!isPlatformMode())
+    return false;
+  if (!isSafari())
+    return false;
+  if (!hasStorageAccessAPI())
+    return false;
+  try {
+    const hasAccess = await document.hasStorageAccess();
+    return !hasAccess;
+  } catch {
+    return false;
+  }
+}
+async function requestStorageAccess() {
+  if (!hasStorageAccessAPI())
+    return false;
+  try {
+    await document.requestStorageAccess();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/fetch.ts
+async function ensureStorageAccess() {
+  if (!isSafari())
+    return true;
+  const needs = await needsStorageAccess();
+  if (needs) {
+    return false;
+  }
+  try {
+    await document.requestStorageAccess();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    return true;
+  } catch (err) {
+    console.error("[Playcademy Auth] Safari Storage Access activation failed:", err);
+    return false;
+  }
+}
+var exchangeComplete = false;
+var exchangePromise = null;
+var TOKEN_POLL_INTERVAL_MS = 50;
+var TOKEN_POLL_MAX_DURATION_MS = 3000;
+async function waitForToken() {
+  const startTime = Date.now();
+  return new Promise((resolve) => {
+    const checkToken = () => {
+      const token = getPlatformToken();
+      if (token) {
+        resolve(token);
+        return;
+      }
+      if (Date.now() - startTime >= TOKEN_POLL_MAX_DURATION_MS) {
+        resolve(null);
+        return;
+      }
+      setTimeout(checkToken, TOKEN_POLL_INTERVAL_MS);
+    };
+    checkToken();
+  });
+}
+function playcademyExchangePlugin(_opts) {
+  return {
+    id: "playcademy-exchange",
+    name: "Playcademy Exchange",
+    async init(url, options) {
+      if (exchangeComplete)
+        return { url, options };
+      if (exchangePromise) {
+        await exchangePromise;
+        return { url, options };
+      }
+      exchangePromise = (async () => {
+        const token = await waitForToken();
+        if (!token)
+          return;
+        const canProceed = await ensureStorageAccess();
+        if (!canProceed) {
+          return;
+        }
+        await fetch("/api/auth/playcademy", {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}` },
+          credentials: "include"
+        });
+        exchangeComplete = true;
+      })();
+      await exchangePromise;
+      return { url, options };
+    }
+  };
+}
+
+// src/client.ts
+var OVERLAY_ID = "playcademy-storage-access-overlay";
+function removeOverlay() {
+  const overlay = document.getElementById(OVERLAY_ID);
+  if (overlay) {
+    overlay.remove();
+  }
+}
+function injectStorageAccessOverlay() {
+  if (document.getElementById(OVERLAY_ID))
+    return;
+  if (!document.body) {
+    document.addEventListener("DOMContentLoaded", injectStorageAccessOverlay);
+    return;
+  }
+  const overlay = document.createElement("div");
+  overlay.id = OVERLAY_ID;
+  overlay.innerHTML = `
+        <style>
+            #${OVERLAY_ID} {
+                position: fixed;
+                top: 0;
+                left: 0;
+                width: 100%;
+                height: 100%;
+                background: rgba(0, 0, 0, 0.8);
+                display: flex;
+                align-items: center;
+                justify-content: center;
+                z-index: 999999;
+                font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            }
+            
+            #${OVERLAY_ID}-modal {
+                background: white;
+                border-radius: 12px;
+                padding: 32px;
+                max-width: 400px;
+                text-align: center;
+                box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+            }
+            
+            #${OVERLAY_ID}-title {
+                font-size: 20px;
+                font-weight: 600;
+                margin: 0 0 12px 0;
+                color: #1a1a1a;
+            }
+            
+            #${OVERLAY_ID}-message {
+                font-size: 14px;
+                line-height: 1.5;
+                margin: 0 0 24px 0;
+                color: #666;
+            }
+            
+            #${OVERLAY_ID}-button {
+                background: #007aff;
+                color: white;
+                border: none;
+                border-radius: 8px;
+                padding: 12px 24px;
+                font-size: 16px;
+                font-weight: 500;
+                cursor: pointer;
+                transition: background 0.2s;
+            }
+            
+            #${OVERLAY_ID}-button:hover {
+                background: #0051d5;
+            }
+            
+            #${OVERLAY_ID}-button:active {
+                transform: scale(0.98);
+            }
+        </style>
+        
+        <div id="${OVERLAY_ID}-modal">
+            <h2 id="${OVERLAY_ID}-title">Enable Authentication</h2>
+            <p id="${OVERLAY_ID}-message">
+                This game needs to store authentication data.<br>
+                Click below to continue.
+            </p>
+            <button id="${OVERLAY_ID}-button">Continue</button>
+        </div>
+    `;
+  const button = overlay.querySelector(`#${OVERLAY_ID}-button`);
+  if (button) {
+    button.addEventListener("click", async () => {
+      if (hasStorageAccessAPI()) {
+        try {
+          const hasAccess = await document.hasStorageAccess();
+          if (hasAccess) {
+            removeOverlay();
+            window.location.reload();
+            return;
+          }
+        } catch {}
+      }
+      const granted = await requestStorageAccess();
+      if (granted) {
+        removeOverlay();
+        window.location.reload();
+      } else {
+        const message = overlay.querySelector(`#${OVERLAY_ID}-message`);
+        if (message) {
+          message.textContent = "Storage access was denied. Please enable cookies in your browser settings to continue.";
+        }
+      }
+    });
+  }
+  document.body.appendChild(overlay);
+}
+async function handleStorageAccess(options) {
+  if (!options.autoPrompt)
+    return;
+  if (!isPlatformMode() || !isSafari())
+    return;
+  const needs = await needsStorageAccess();
+  if (needs) {
+    injectStorageAccessOverlay();
+  }
+}
+function playcademy(options) {
+  const opts = {
+    safari: {
+      autoPrompt: options?.safari?.autoPrompt ?? true
+    }
+  };
+  if (typeof window !== "undefined" && opts.safari.autoPrompt) {
+    if (isPlatformMode() && isSafari()) {
+      setTimeout(() => {
+        handleStorageAccess(opts.safari);
+      }, 0);
+    }
+  }
+  return {
+    id: "playcademy-client",
+    $InferServerPlugin: {},
+    fetchPlugins: [playcademyExchangePlugin()]
+  };
+}
+export {
+  playcademy
+};

package/dist/fetch.d.ts

@@ -0,0 +1,10 @@
+import type { BetterFetchPlugin } from '@better-fetch/fetch';
+/**
+ * Better Auth fetch plugin - exchanges platform token on first request
+ *
+ * Uses polling strategy (similar to bootIframe handshake) to wait for SDK initialization.
+ * This keeps Better Auth completely decoupled from our SDK.
+ */
+export declare function playcademyExchangePlugin(_opts?: {
+    baseURL: string;
+}): BetterFetchPlugin;

package/dist/server.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Playcademy plugin for Better Auth
+ *
+ * This plugin provides:
+ * - Platform user schema field (playcademyUserId)
+ * - Token exchange endpoint (POST /api/auth/playcademy)
+ * - Automatic account linking between platform and standalone modes
+ * - Cross-site cookie support with CHIPS
+ *
+ * @example
+ * ```typescript
+ * import { betterAuth } from 'better-auth'
+ * import { playcademy } from '@playcademy/better-auth/server'
+ *
+ * export const auth = betterAuth({
+ *   database: drizzleAdapter(db, { provider: 'sqlite' }),
+ *   plugins: [playcademy()],
+ *   advanced: {
+ *     defaultCookieAttributes: {
+ *       sameSite: 'none',
+ *       secure: true,
+ *       path: '/',
+ *       partitioned: true, // CHIPS for Chrome/Edge
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare const playcademy: () => {
+    id: "playcademy";
+    schema: {
+        user: {
+            fields: {
+                playcademyUserId: {
+                    type: "string";
+                    unique: true;
+                    required: false;
+                };
+            };
+        };
+    };
+    endpoints: {
+        /**
+         * Platform Token Exchange Endpoint
+         *
+         * POST /api/auth/playcademy
+         *
+         * Exchanges a Playcademy platform JWT for a Better Auth session.
+         * Used when games are launched from the platform (iframe mode).
+         *
+         * Flow:
+         * 1. Verify platform JWT with platform API
+         * 2. Find or create user (with account linking)
+         * 3. Check if already authenticated
+         * 4. Create new session if needed
+         * 5. Set cross-site compatible cookie (CHIPS)
+         */
+        playcademyAuth: {
+            <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0?: ({
+                body?: undefined;
+            } & {
+                method?: "POST" | undefined;
+            } & {
+                query?: Record<string, any> | undefined;
+            } & {
+                params?: Record<string, any>;
+            } & {
+                request?: Request;
+            } & {
+                headers?: HeadersInit;
+            } & {
+                asResponse?: boolean;
+                returnHeaders?: boolean;
+                use?: import("better-call").Middleware[];
+                path?: string;
+            } & {
+                asResponse?: AsResponse | undefined;
+                returnHeaders?: ReturnHeaders | undefined;
+            }) | undefined): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+                headers: Headers;
+                response: Response;
+            } : Response>;
+            options: {
+                method: "POST";
+                requireHeaders: false;
+            } & {
+                use: any[];
+            };
+            path: "/playcademy";
+        };
+    };
+};