@authgate/browser 0.3.0 → 0.4.0

package/README.md

@@ -24,7 +24,7 @@ framework-specific abstractions.
 
 - Read AuthGate CSRF token from browser cookies
 - Perform a CSRF-protected logout request
-- Explicit browser-side session refresh
+- Explicit browser-side session refresh **with audience selection**
 - Optional `fetch` wrapper with **single-retry refresh semantics**
 - Clear success / failure signaling
 - Optional redirect on logout
@@ -57,7 +57,7 @@ It does not generate or validate it.
 
 ---
 
-### Logout
+## Logout
 
 ```ts
 import { logout } from "@authgate/browser";
@@ -103,16 +103,28 @@ Redirecting is an optional side-effect and does **not** define success.
 ```ts
 import { refreshSession } from "@authgate/browser";
 
-const refreshed = await refreshSession();
+const refreshed = await refreshSession("app");
 ```
 
 Attempts to refresh the current AuthGate session by calling:
 
-```
+```text
 POST /auth/refresh
 ```
 
-Behavior:
+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
@@ -141,16 +153,25 @@ const res = await authFetch("/api/data");
 `authFetch` is an **optional convenience wrapper** around `fetch` with
 AuthGate-aware refresh behavior.
 
-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()`
+   - Attempts `refreshSession()` with the same audience
    - If refresh succeeds, retries the original request **once**
    - Otherwise, returns the original `401` response
 
-Important properties:
+### 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
@@ -171,6 +192,16 @@ if (res.status === 401) {
 }
 ```
 
+Admin request:
+
+```ts
+const res = await authFetch(
+  "/admin/api/users",
+  {},
+  { audience: "admin" },
+);
+```
+
 ---
 
 ## Security model
@@ -179,6 +210,7 @@ if (res.status === 401) {
 - CSRF validation is **enforced by AuthGate**
 - Refresh tokens are **never exposed to JavaScript**
 - All authentication state is owned by AuthGate
+- Audiences are **explicitly requested and server-validated**
 
 This package only forwards existing browser state explicitly.
 
@@ -202,6 +234,7 @@ while preserving full application control.
 ## Compatibility
 
 - Works with any backend protected by AuthGate
+- Supports SSR, SPA, and hybrid architectures
 
 ---
 

package/dist/index.d.ts

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

package/dist/index.js

@@ -68,22 +68,35 @@ export async function logout(opts) {
     return { ok: true };
 }
 /**
- * authFetch performs a fetch request with AuthGate-aware refresh-once behavior.
+ * authFetch performs a fetch request with AuthGate-aware, refresh-once behavior
+ * for a specific audience.
  *
  * Behavior:
  * - Always includes credentials
- * - If the response is NOT 401 - returns it directly
+ * - 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
- *   - If refresh succeeds - retries original request ONCE
- *   - Otherwise - returns original 401 response
+ *   - 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 = {}) {
+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();
+    const refreshed = await refreshSession(audience);
     if (!refreshed) {
         return res;
     }
@@ -96,24 +109,29 @@ function withCredentials(init) {
     };
 }
 /**
- * refreshSession attempts to refresh the current AuthGate session.
+ * refreshSession attempts to refresh the current AuthGate session for a
+ * specific audience.
  *
  * It performs:
  *   POST /auth/refresh
- *   with CSRF protection and credentials
+ *   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.
  *
- * The function:
- * - returns true if refresh succeeded
- * - returns false if refresh failed for any reason
+ * @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() {
+export async function refreshSession(audience = "app") {
     const csrf = getCSRFToken();
     if (!csrf) {
         return false;
     }
     let res;
     try {
-        res = await fetch("/auth/refresh", {
+        res = await fetch(`/auth/refresh?audience=${encodeURIComponent(audience)}`, {
             method: "POST",
             headers: {
                 "X-CSRF-Token": csrf,

package/package.json

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