@authgate/browser 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Lupatsiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,18 +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 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
 
 ---
 
@@ -37,6 +52,9 @@ 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.
+
 ---
 
 ### Logout
@@ -44,7 +62,7 @@ Returns the value of the `authgate_csrf` cookie, or `null` if not present.
 ```ts
 import { logout } from "@authgate/browser";
 
-await logout();
+const result = await logout();
 ```
 
 This will:
@@ -53,6 +71,17 @@ This will:
 - Attach the CSRF token via `X-CSRF-Token`
 - Include credentials (`cookies`)
 
+The function returns an explicit result:
+
+```ts
+type LogoutResult =
+  | { ok: true }
+  | { ok: false; reason: "missing_csrf" | "request_failed" | "unauthorized" };
+```
+
+Applications that do not need to react programmatically may safely ignore the
+return value.
+
 ---
 
 ### Logout with redirect
@@ -61,41 +90,119 @@ This will:
 await logout({ redirectTo: "/" });
 ```
 
-After a successful logout request, the browser is redirected to the given path.
+If the logout request succeeds, the browser is redirected to the given path.
+
+Redirecting is an optional side-effect and does **not** define success.
+
+---
+
+## Session refresh (explicit)
+
+### `refreshSession`
+
+```ts
+import { refreshSession } from "@authgate/browser";
+
+const refreshed = await refreshSession();
+```
+
+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.
 
 ---
 
-## Security Model
+## 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);
+}
+```
+
+---
+
+## 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 redirects except when explicitly requested
+- 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
-- Safe to use in multi-app or monorepo setups
 
 ---
 
 ## License
-
-MIT
-

package/dist/index.d.ts

@@ -1,4 +1,64 @@
+/**
+ * Returns the AuthGate CSRF token from the browser cookies.
+ *
+ * The CSRF token is issued by AuthGate and stored in the `authgate_csrf`
+ * cookie. This helper does not validate the token; it only reads it.
+ *
+ * @returns The CSRF token string, or `null` if the cookie is missing.
+ */
 export declare function getCSRFToken(): string | null;
+/**
+ * The result of a logout attempt.
+ *
+ * - `{ ok: true }` indicates that logout succeeded.
+ * - `{ ok: false, reason }` indicates that logout failed for a known reason.
+ */
+type LogoutResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "missing_csrf" | "request_failed" | "unauthorized";
+};
+/**
+ * Logs the user out by calling the AuthGate logout endpoint.
+ *
+ * This function:
+ * - Reads the CSRF token from the browser cookies
+ * - Sends a POST request to `/auth/logout`
+ * - Optionally redirects the browser on success
+ *
+ * Redirecting is a side-effect and does not define success. Applications
+ * that need to react to logout programmatically (e.g. SPA state updates)
+ * should inspect the returned result instead.
+ *
+ * @param opts.redirectTo Optional URL to redirect to after successful logout.
+ * @returns A `LogoutResult` indicating whether logout succeeded or failed.
+ */
 export declare function logout(opts?: {
     redirectTo?: string;
-}): Promise<void>;
+}): 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

@@ -1,22 +1,128 @@
+/**
+ * Reads a cookie value by name from `document.cookie`.
+ *
+ * This is a small internal helper used by the AuthGate browser SDK.
+ * It returns `null` if the cookie is not present.
+ */
 function getCookie(name) {
     const match = document.cookie
         .split("; ")
         .find((c) => c.startsWith(name + "="));
     return match ? decodeURIComponent(match.split("=")[1]) : null;
 }
+/**
+ * Returns the AuthGate CSRF token from the browser cookies.
+ *
+ * The CSRF token is issued by AuthGate and stored in the `authgate_csrf`
+ * cookie. This helper does not validate the token; it only reads it.
+ *
+ * @returns The CSRF token string, or `null` if the cookie is missing.
+ */
 export function getCSRFToken() {
     return getCookie("authgate_csrf");
 }
+/**
+ * Logs the user out by calling the AuthGate logout endpoint.
+ *
+ * This function:
+ * - Reads the CSRF token from the browser cookies
+ * - Sends a POST request to `/auth/logout`
+ * - Optionally redirects the browser on success
+ *
+ * Redirecting is a side-effect and does not define success. Applications
+ * that need to react to logout programmatically (e.g. SPA state updates)
+ * should inspect the returned result instead.
+ *
+ * @param opts.redirectTo Optional URL to redirect to after successful logout.
+ * @returns A `LogoutResult` indicating whether logout succeeded or failed.
+ */
 export async function logout(opts) {
     const csrf = getCSRFToken();
-    await fetch("/auth/logout", {
-        method: "POST",
-        headers: {
-            "X-CSRF-Token": csrf ?? "",
-        },
-        credentials: "include",
-    });
-    if (opts?.redirectTo !== undefined) {
+    if (!csrf) {
+        return { ok: false, reason: "missing_csrf" };
+    }
+    let res;
+    try {
+        res = await fetch("/auth/logout", {
+            method: "POST",
+            headers: {
+                "X-CSRF-Token": csrf,
+            },
+            credentials: "include",
+        });
+    }
+    catch {
+        return { ok: false, reason: "request_failed" };
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            reason: res.status === 401 || res.status === 403
+                ? "unauthorized"
+                : "request_failed",
+        };
+    }
+    if (opts?.redirectTo) {
         window.location.href = opts.redirectTo;
     }
+    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

@@ -1,6 +1,10 @@
 {
   "name": "@authgate/browser",
-  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexlup06-authgate/authgate-browser.git"
+  },
+  "version": "0.3.0",
   "description": "Browser-side helpers for AuthGate (logout, CSRF forwarding)",
   "license": "MIT",
   "type": "module",