@authgate/browser 0.2.0 → 0.4.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 **with audience selection**
+- Optional `fetch` wrapper with **single-retry refresh semantics**
+- Clear success / failure signaling
+- Optional redirect on logout
+- No runtime dependencies
 
 ---
 
@@ -39,11 +52,12 @@ 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.
 
 ---
 
-### Logout
+## Logout
 
 ```ts
 import { logout } from "@authgate/browser";
@@ -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,149 @@ 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("app");
+```
+
+Attempts to refresh the current AuthGate session by calling:
+
+```text
+POST /auth/refresh
+```
+
+with an explicit **audience declaration**.
+
+### Audience
+
+The audience determines **which access token is minted** (e.g. `"app"`, `"admin"`).
+
+- The client explicitly requests an audience
+- AuthGate validates the requested audience against the user’s roles
+- Requests for unauthorized audiences fail with `401`
+
+If no audience is provided, `"app"` is used by default.
+
+### 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)
 
-if (result.ok) {
+### `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()` with the same audience
+   - If refresh succeeds, retries the original request **once**
+   - Otherwise, returns the original `401` response
+
+### Audience-aware requests
+
+```ts
+await authFetch("/admin/api/users", {}, { audience: "admin" });
+```
+
+- The same audience is used for the refresh attempt
+- Unauthorized audiences fail cleanly without retry loops
+
+### 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);
 }
 ```
 
+Admin request:
+
+```ts
+const res = await authFetch(
+  "/admin/api/users",
+  {},
+  { audience: "admin" },
+);
+```
+
 ---
 
-## 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
+- Audiences are **explicitly requested and server-validated**
 
-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
+- Supports SSR, SPA, and hybrid architectures
 
 ---
 
 ## License
-
-MIT
-

package/dist/index.d.ts

@@ -37,4 +37,47 @@ type LogoutResult = {
 export declare function logout(opts?: {
     redirectTo?: string;
 }): Promise<LogoutResult>;
+/**
+ * authFetch performs a fetch request with AuthGate-aware, refresh-once behavior
+ * for a specific audience.
+ *
+ * Behavior:
+ * - Always includes credentials
+ * - Performs the initial request as-is
+ * - If the response is NOT 401, returns it directly
+ * - If the response IS 401:
+ *   - Attempts POST /auth/refresh with CSRF and the same requested audience
+ *   - If refresh succeeds, retries the original request ONCE
+ *   - If refresh fails, returns the original 401 response
+ *
+ * authFetch never redirects or mutates application state. Callers are expected
+ * to handle authentication failures explicitly.
+ *
+ * @param input The resource to fetch (same as `fetch`).
+ * @param init Optional fetch options. Credentials are always included.
+ * @param opts Optional AuthGate options.
+ * @param opts.audience The audience for which the request is made (e.g. "app", "admin").
+ *        Defaults to "app".
+ * @returns The final `Response` from the original request or the retried request.
+ */
+export declare function authFetch(input: RequestInfo | URL, init?: RequestInit, opts?: {
+    audience?: string;
+}): Promise<Response>;
+/**
+ * refreshSession attempts to refresh the current AuthGate session for a
+ * specific audience.
+ *
+ * It performs:
+ *   POST /auth/refresh
+ *   with CSRF protection, credentials, and an explicit audience declaration.
+ *
+ * The server validates the requested audience against the user's roles and
+ * rejects the request if the audience is not permitted.
+ *
+ * @param audience The audience for which a new access token should be minted.
+ *        Defaults to "app".
+ * @returns `true` if the refresh succeeded, or `false` if refresh failed for
+ *          any reason (unauthorized, expired session, or error).
+ */
+export declare function refreshSession(audience?: string): Promise<boolean>;
 export {};

package/dist/index.js

@@ -67,3 +67,80 @@ export async function logout(opts) {
     }
     return { ok: true };
 }
+/**
+ * authFetch performs a fetch request with AuthGate-aware, refresh-once behavior
+ * for a specific audience.
+ *
+ * Behavior:
+ * - Always includes credentials
+ * - Performs the initial request as-is
+ * - If the response is NOT 401, returns it directly
+ * - If the response IS 401:
+ *   - Attempts POST /auth/refresh with CSRF and the same requested audience
+ *   - If refresh succeeds, retries the original request ONCE
+ *   - If refresh fails, returns the original 401 response
+ *
+ * authFetch never redirects or mutates application state. Callers are expected
+ * to handle authentication failures explicitly.
+ *
+ * @param input The resource to fetch (same as `fetch`).
+ * @param init Optional fetch options. Credentials are always included.
+ * @param opts Optional AuthGate options.
+ * @param opts.audience The audience for which the request is made (e.g. "app", "admin").
+ *        Defaults to "app".
+ * @returns The final `Response` from the original request or the retried request.
+ */
+export async function authFetch(input, init = {}, opts) {
+    const audience = opts?.audience ?? "app";
+    const res = await fetch(input, withCredentials(init));
+    if (res.status !== 401) {
+        return res;
+    }
+    const refreshed = await refreshSession(audience);
+    if (!refreshed) {
+        return res;
+    }
+    return fetch(input, withCredentials(init));
+}
+function withCredentials(init) {
+    return {
+        ...init,
+        credentials: "include",
+    };
+}
+/**
+ * refreshSession attempts to refresh the current AuthGate session for a
+ * specific audience.
+ *
+ * It performs:
+ *   POST /auth/refresh
+ *   with CSRF protection, credentials, and an explicit audience declaration.
+ *
+ * The server validates the requested audience against the user's roles and
+ * rejects the request if the audience is not permitted.
+ *
+ * @param audience The audience for which a new access token should be minted.
+ *        Defaults to "app".
+ * @returns `true` if the refresh succeeded, or `false` if refresh failed for
+ *          any reason (unauthorized, expired session, or error).
+ */
+export async function refreshSession(audience = "app") {
+    const csrf = getCSRFToken();
+    if (!csrf) {
+        return false;
+    }
+    let res;
+    try {
+        res = await fetch(`/auth/refresh?audience=${encodeURIComponent(audience)}`, {
+            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.4.0",
   "description": "Browser-side helpers for AuthGate (logout, CSRF forwarding)",
   "license": "MIT",
   "type": "module",