@everystack/auth 0.2.2 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/auth",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "JWT authentication handlers, password hashing, and React auth context",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/client/index.tsx

@@ -11,7 +11,7 @@
  *   const { user, token, signIn, signUp, signOut, isLoading } = useAuth();
  */
 
-import React, { createContext, useContext, useState, useEffect, useCallback } from 'react';
+import React, { createContext, useContext, useState, useEffect, useCallback, useRef } from 'react';
 import { refreshAuthToken } from '../api';
 
 export interface AuthUser {
@@ -81,11 +81,26 @@ export function isTokenExpired(token: string): boolean {
   } catch { return true; }
 }
 
-export function AuthProvider({ children }: { children: React.ReactNode }): React.ReactElement {
+export interface AuthProviderProps {
+  children: React.ReactNode;
+  /**
+   * Called after a successful auth transition — the seam for product-analytics
+   * emitters (e.g. createAnalyticsClient().track('login')). Optional; kept generic
+   * so the auth package never depends on the analytics client.
+   */
+  onAuthEvent?: (event: 'login' | 'signup' | 'logout', user: AuthUser | null) => void;
+}
+
+export function AuthProvider({ children, onAuthEvent }: AuthProviderProps): React.ReactElement {
   const [user, setUser] = useState<AuthUser | null>(null);
   const [token, setToken] = useState<string | null>(null);
   const [isLoading, setIsLoading] = useState(true);
 
+  // Ref-backed so signIn/signUp/signOut stay stable (no dep churn) yet always
+  // call the latest handler.
+  const onAuthEventRef = useRef(onAuthEvent);
+  onAuthEventRef.current = onAuthEvent;
+
   useEffect(() => {
     const init = async () => {
       const savedToken = storage.getToken();
@@ -129,6 +144,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }): React
     storage.save(body.token, body.refreshToken, body.user);
     setToken(body.token);
     setUser(body.user);
+    onAuthEventRef.current?.('login', body.user);
   }, []);
 
   const signUp = useCallback(async (email: string, password: string, username: string, displayName: string) => {
@@ -147,11 +163,13 @@ export function AuthProvider({ children }: { children: React.ReactNode }): React
     storage.save(body.token, body.refreshToken, body.user);
     setToken(body.token);
     setUser(body.user);
+    onAuthEventRef.current?.('signup', body.user);
   }, []);
 
   const signOut = useCallback(() => {
     // Clear server-side cookies (best-effort, don't block UI)
     fetch('/api/auth/signout', { method: 'POST' }).catch(() => {});
+    onAuthEventRef.current?.('logout', storage.getUser());
     storage.clear();
     setToken(null);
     setUser(null);

package/src/cookies.ts

@@ -3,7 +3,11 @@
  *
  * Access token cookie is sent on all requests (Path=/).
  * Refresh token cookie is scoped to the refresh endpoint only (Path=/api/auth/refresh).
- * Both are HttpOnly + Secure + SameSite=Lax.
+ *
+ * Access token is SameSite=Lax — it must ride top-level SSR navigations into the
+ * app. Refresh token is SameSite=Strict — it is only ever hit by XHR at its scoped
+ * path, never a navigation target, so Strict kills its CSRF surface by construction
+ * (a cross-site page can't make the browser attach it at all).
  */
 
 export const COOKIE_NAMES = {
@@ -44,7 +48,7 @@ export function serializeAuthCookies(
 
   return [
     `${COOKIE_NAMES.token}=${token}; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Lax; Path=${basePath}; Max-Age=${tokenMaxAge}${domain}`,
-    `${COOKIE_NAMES.refresh}=${refreshToken}; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Lax; Path=/api/auth/refresh; Max-Age=${refreshMaxAge}${domain}`,
+    `${COOKIE_NAMES.refresh}=${refreshToken}; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Strict; Path=/api/auth/refresh; Max-Age=${refreshMaxAge}${domain}`,
   ];
 }
 
@@ -58,7 +62,7 @@ export function clearAuthCookies(opts?: CookieOptions): string[] {
 
   return [
     `${COOKIE_NAMES.token}=; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Lax; Path=${basePath}; Max-Age=0${domain}`,
-    `${COOKIE_NAMES.refresh}=; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Lax; Path=/api/auth/refresh; Max-Age=0${domain}`,
+    `${COOKIE_NAMES.refresh}=; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Strict; Path=/api/auth/refresh; Max-Age=0${domain}`,
   ];
 }
 

package/src/index.ts

@@ -180,6 +180,32 @@ function csrfCheck(request: Request, cookies?: CookieConfig): Response | null {
   return validateCsrfOrigin(request, cookies.allowedOrigins);
 }
 
+/**
+ * Fail-closed cookie config check, run once at handler construction.
+ *
+ * Cookie-authenticated requests carry a CSRF surface (the cookie is auto-sent).
+ * The Origin allowlist is the defense-in-depth behind SameSite — and it silently
+ * no-ops when `allowedOrigins` is empty, so enabling cookies without it would turn
+ * the CSRF check off without any signal. We refuse to start instead: a misconfig
+ * dies at deploy, not silently-allows until a request happens to hit the check.
+ *
+ * The `cookies: true` shorthand cannot carry an allowlist, so it is rejected —
+ * there is no construction-time same-origin to derive. Pass an explicit allowlist
+ * or omit cookies entirely for Bearer-only (mobile/API) auth.
+ */
+function assertSafeCookieConfig(cookies: CookieConfig | undefined): void {
+  if (!cookies) return; // cookie auth disabled (false/undefined) — Bearer-only, no CSRF surface
+  const allowedOrigins = cookies === true ? undefined : cookies.allowedOrigins;
+  if (!allowedOrigins || allowedOrigins.length === 0) {
+    throw new Error(
+      '[everystack/auth] Cookie authentication is enabled but cookies.allowedOrigins is empty. '
+      + 'Cookie-authenticated requests carry a CSRF surface; an explicit Origin allowlist is '
+      + 'required. Pass cookies: { allowedOrigins: ["https://your-web-origin"] } instead of '
+      + 'cookies: true, or omit cookies for Bearer-only (mobile/API) auth.'
+    );
+  }
+}
+
 /**
  * Add mode-independent email confirmation and password management handlers.
  * Called after base handlers are created (works with both node and postgres modes).
@@ -389,6 +415,8 @@ export function createAuthHandlers(
   jwtSecret: Uint8Array,
   options?: AuthOptions
 ): AuthHandlers {
+  assertSafeCookieConfig(options?.cookies);
+
   if (options?.mode === 'postgres') {
     const handlers = createPostgresAuthHandlers(db, schema, jwtSecret, options);
     addEmailPasswordFlows(handlers, db, schema.users, options);

package/src/plugin.ts

@@ -176,33 +176,44 @@ export function authPlugin(options: AuthPluginOptions = {}): Plugin {
 
     // --- Wire enrichClaims ref ---
     const authCtx = ctx as AuthContext;
-    if (authCtx.enrichClaimsRef && clientCallbacks) {
+    if (authCtx.enrichClaimsRef && (clientCallbacks || options.audience)) {
       authCtx.enrichClaimsRef.current = async (
         baseClaims: Record<string, unknown>,
         request: Request,
       ): Promise<Record<string, unknown>> => {
-        // Check baseClaims first (refresh path — client_id from session data)
-        let clientId = baseClaims.client_id as string | undefined;
-
-        // Fall back to request body (signin/signup path)
-        if (!clientId) {
-          try {
-            const body = await request.clone().json();
-            clientId = body?.client_id;
-          } catch {
-            // No JSON body or no client_id
+        if (clientCallbacks) {
+          // Check baseClaims first (refresh path — client_id from session data)
+          let clientId = baseClaims.client_id as string | undefined;
+
+          // Fall back to request body (signin/signup path)
+          if (!clientId) {
+            try {
+              const body = await request.clone().json();
+              clientId = body?.client_id;
+            } catch {
+              // No JSON body or no client_id
+            }
           }
-        }
-
-        if (!clientId) return {};
 
-        const client = await clientCallbacks.resolve(clientId);
-        if (!client || !client.active) return {};
+          if (clientId) {
+            // An explicit client_id is an assertion of client-credential auth:
+            // unknown or revoked clients get no claims, so under an audience
+            // config their tokens fail verification — never a silent downgrade
+            // to first-party.
+            const client = await clientCallbacks.resolve(clientId);
+            if (!client || !client.active) return {};
+
+            return {
+              client_id: clientId,
+              aud: client.audience ?? options.audience,
+            };
+          }
+        }
 
-        return {
-          client_id: clientId,
-          aud: client.audience ?? options.audience,
-        };
+        // First-party signin/refresh: tokens this app issues for its own
+        // users carry the app audience — the audience layer rejects any
+        // token without it, including the ones we mint ourselves.
+        return options.audience ? { aud: options.audience } : {};
       };
     }