@authgate/browser 0.2.0 → 0.3.0

package/README.md

@@ -2,20 +2,33 @@
 
 Minimal browser-side helpers for applications using **AuthGate**.
 
-This package provides small, explicit utilities to integrate browser-based UIs
-with an AuthGate-backed authentication flow. It intentionally avoids framework
-coupling and hidden behavior.
+This package provides **explicit, framework-agnostic primitives** for integrating
+browser-based UIs (SSR or SPA) with an AuthGate-backed authentication system.
+
+It intentionally avoids hidden behavior, background state mutation, or
+framework-specific abstractions.
 
 ---
 
-## Features
+## Design goals
 
-- Read AuthGate CSRF token from cookies
-- Perform a safe logout request with CSRF protection
-- Explicit success/failure signaling
-- Optional redirect after logout
+- Explicit behavior (no magic, no background auth)
+- Browser-only responsibility (cookies, CSRF, refresh)
+- Framework-agnostic (React, Vue, Svelte, vanilla JS)
+- Composable primitives + optional convenience helpers
 - Zero dependencies
-- Framework-agnostic (works with React, Vue, vanilla JS, etc.)
+
+---
+
+## Features
+
+- Read AuthGate CSRF token from browser cookies
+- Perform a CSRF-protected logout request
+- Explicit browser-side session refresh
+- Optional `fetch` wrapper with **single-retry refresh semantics**
+- Clear success / failure signaling
+- Optional redirect on logout
+- No runtime dependencies
 
 ---
 
@@ -39,7 +52,8 @@ const csrf = getCSRFToken();
 
 Returns the value of the `authgate_csrf` cookie, or `null` if not present.
 
-This function only **reads** the CSRF token. It does not generate or validate it.
+This function only **reads** the CSRF token.  
+It does not generate or validate it.
 
 ---
 
@@ -57,7 +71,7 @@ This will:
 - Attach the CSRF token via `X-CSRF-Token`
 - Include credentials (`cookies`)
 
-The function returns a result indicating whether logout succeeded:
+The function returns an explicit result:
 
 ```ts
 type LogoutResult =
@@ -65,8 +79,8 @@ type LogoutResult =
   | { ok: false; reason: "missing_csrf" | "request_failed" | "unauthorized" };
 ```
 
-Applications that do not need to react programmatically to logout may safely
-ignore the return value.
+Applications that do not need to react programmatically may safely ignore the
+return value.
 
 ---
 
@@ -79,54 +93,116 @@ await logout({ redirectTo: "/" });
 If the logout request succeeds, the browser is redirected to the given path.
 
 Redirecting is an optional side-effect and does **not** define success.
-Applications may choose to handle navigation themselves instead.
 
 ---
 
-### Example (React / SPA)
+## Session refresh (explicit)
+
+### `refreshSession`
 
 ```ts
-const result = await logout();
+import { refreshSession } from "@authgate/browser";
+
+const refreshed = await refreshSession();
+```
 
-if (result.ok) {
+Attempts to refresh the current AuthGate session by calling:
+
+```
+POST /auth/refresh
+```
+
+Behavior:
+
+- Returns `true` if refresh succeeded
+- Returns `false` if refresh failed for any reason
+
+This function:
+
+- does **not** retry
+- does **not** redirect
+- does **not** throw
+- does **not** modify application state
+
+It is intended for applications that want **manual control** over refresh logic.
+
+---
+
+## Fetch wrapper (optional convenience)
+
+### `authFetch`
+
+```ts
+import { authFetch } from "@authgate/browser";
+
+const res = await authFetch("/api/data");
+```
+
+`authFetch` is an **optional convenience wrapper** around `fetch` with
+AuthGate-aware refresh behavior.
+
+Behavior:
+
+1. Performs the request with credentials
+2. If the response is **not `401`**, returns it directly
+3. If the response **is `401`**:
+   - Attempts `refreshSession()`
+   - If refresh succeeds, retries the original request **once**
+   - Otherwise, returns the original `401` response
+
+Important properties:
+
+- At most **one retry**
+- No redirects
+- No background refresh
+- No swallowed failures
+
+Applications remain fully in control of UX decisions.
+
+---
+
+## Example (React / SPA)
+
+```ts
+const res = await authFetch("/api/me");
+
+if (res.status === 401) {
   setUser(null);
-} else {
-  console.error("Logout failed:", result.reason);
 }
 ```
 
 ---
 
-## Security Model
+## Security model
 
 - CSRF tokens are **not generated** by this package
 - CSRF validation is **enforced by AuthGate**
-- This package only forwards existing CSRF state
+- Refresh tokens are **never exposed to JavaScript**
+- All authentication state is owned by AuthGate
 
-No cookies are set, modified, or cleared by this library.
+This package only forwards existing browser state explicitly.
 
 ---
 
-## What This Package Does NOT Do
+## What this package does NOT do
 
 - No authentication logic
-- No token refresh
+- No credential storage
+- No background token refresh
 - No session management
+- No authorization or role handling
 - No implicit redirects
 - No framework-specific helpers
 
-This package exists solely to reduce boilerplate and prevent integration mistakes.
+This package exists solely to reduce boilerplate and prevent integration mistakes
+while preserving full application control.
 
 ---
 
 ## Compatibility
 
 - Works with any backend protected by AuthGate
-- Compatible with SSR and SPA architectures
 
 ---
 
 ## License
-
-MIT
-

package/dist/index.d.ts

@@ -37,4 +37,28 @@ type LogoutResult = {
 export declare function logout(opts?: {
     redirectTo?: string;
 }): Promise<LogoutResult>;
+/**
+ * authFetch performs a fetch request with AuthGate-aware refresh-once behavior.
+ *
+ * Behavior:
+ * - Always includes credentials
+ * - If the response is NOT 401 - returns it directly
+ * - If the response IS 401:
+ *   - Attempts POST /auth/refresh with CSRF
+ *   - If refresh succeeds - retries original request ONCE
+ *   - Otherwise - returns original 401 response
+ */
+export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+/**
+ * refreshSession attempts to refresh the current AuthGate session.
+ *
+ * It performs:
+ *   POST /auth/refresh
+ *   with CSRF protection and credentials
+ *
+ * The function:
+ * - returns true if refresh succeeded
+ * - returns false if refresh failed for any reason
+ */
+export declare function refreshSession(): Promise<boolean>;
 export {};

package/dist/index.js

@@ -67,3 +67,62 @@ export async function logout(opts) {
     }
     return { ok: true };
 }
+/**
+ * authFetch performs a fetch request with AuthGate-aware refresh-once behavior.
+ *
+ * Behavior:
+ * - Always includes credentials
+ * - If the response is NOT 401 - returns it directly
+ * - If the response IS 401:
+ *   - Attempts POST /auth/refresh with CSRF
+ *   - If refresh succeeds - retries original request ONCE
+ *   - Otherwise - returns original 401 response
+ */
+export async function authFetch(input, init = {}) {
+    const res = await fetch(input, withCredentials(init));
+    if (res.status !== 401) {
+        return res;
+    }
+    const refreshed = await refreshSession();
+    if (!refreshed) {
+        return res;
+    }
+    return fetch(input, withCredentials(init));
+}
+function withCredentials(init) {
+    return {
+        ...init,
+        credentials: "include",
+    };
+}
+/**
+ * refreshSession attempts to refresh the current AuthGate session.
+ *
+ * It performs:
+ *   POST /auth/refresh
+ *   with CSRF protection and credentials
+ *
+ * The function:
+ * - returns true if refresh succeeded
+ * - returns false if refresh failed for any reason
+ */
+export async function refreshSession() {
+    const csrf = getCSRFToken();
+    if (!csrf) {
+        return false;
+    }
+    let res;
+    try {
+        res = await fetch("/auth/refresh", {
+            method: "POST",
+            headers: {
+                "X-CSRF-Token": csrf,
+            },
+            credentials: "include",
+        });
+    }
+    catch {
+        return false;
+    }
+    return res.ok;
+}

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/alexlup06-authgate/authgate-browser.git"
   },
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Browser-side helpers for AuthGate (logout, CSRF forwarding)",
   "license": "MIT",
   "type": "module",