@auditauth/web 0.2.0-beta.1

package/README.md

@@ -0,0 +1,108 @@
+# @auditauth/web
+
+`@auditauth/web` is the framework-agnostic AuditAuth SDK for browser
+applications. It handles login redirects, callback processing, session state,
+token refresh, and request and navigation metrics.
+
+## Install
+
+Install the package in your app.
+
+```bash
+npm install @auditauth/web
+```
+
+## Create an SDK instance
+
+Create one `AuditAuthWeb` instance with your AuditAuth config and a storage
+adapter. In browser apps, local storage is the common default.
+
+```ts
+import { AuditAuthWeb } from '@auditauth/web'
+
+export const auditauth = new AuditAuthWeb(
+  {
+    apiKey: process.env.VITE_AUDITAUTH_API_KEY!,
+    appId: process.env.VITE_AUDITAUTH_APP_ID!,
+    baseUrl: 'http://localhost:5173',
+    redirectUrl: 'http://localhost:5173/private',
+  },
+  {
+    get: (name) => localStorage.getItem(name),
+    set: (name, value) => localStorage.setItem(name, value),
+    remove: (name) => localStorage.removeItem(name),
+  }
+)
+```
+
+## Initialize on app startup
+
+Handle callback redirects before rendering protected pages, then enable
+navigation tracking.
+
+```ts
+await auditauth.handleRedirect()
+auditauth.initNavigationTracking()
+```
+
+## Protect private pages
+
+Before rendering private views, check if the user has a session. If not,
+redirect to login.
+
+```ts
+if (!auditauth.isAuthenticated()) {
+  await auditauth.login()
+}
+```
+
+You can access the current user at any time with `auditauth.getSessionUser()`.
+
+## Make authenticated API calls
+
+Use `auditauth.fetch()` instead of `window.fetch()` for authenticated requests.
+The SDK attaches the access token and automatically attempts refresh when a
+request returns `401`.
+
+```ts
+const response = await auditauth.fetch('https://api.example.com/private')
+```
+
+## Use session actions
+
+You can trigger user session actions from your UI.
+
+- `auditauth.login()` starts the login flow
+- `auditauth.logout()` revokes and clears the session
+- `auditauth.goToPortal()` redirects to the AuditAuth portal
+
+## API reference
+
+These methods are available in `AuditAuthWeb`.
+
+- `handleRedirect(): Promise<void | null>`
+- `isAuthenticated(): boolean`
+- `getSessionUser(): SessionUser | null`
+- `login(): Promise<void>`
+- `logout(): Promise<void>`
+- `goToPortal(): Promise<void>`
+- `fetch(input, init?): Promise<Response>`
+- `trackNavigationPath(path: string): void`
+- `initNavigationTracking(): void`
+
+## Compatibility
+
+This package requires Node.js `>=18.18.0` for tooling and build environments.
+
+## Resources
+
+- Repository: https://github.com/nimibyte/auditauth-sdk
+- Documentation: https://docs.auditauth.com
+
+## Example
+
+See the complete integration in `examples/vanilla/src`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sdk';
+export type * from './types';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './sdk';

package/dist/sdk.d.ts

@@ -0,0 +1,21 @@
+import { AuditAuthConfig } from "@auditauth/core";
+import { StorageAdapter } from "./types";
+declare class AuditAuthWeb {
+    private config;
+    private storage;
+    constructor(config: AuditAuthConfig, storage: StorageAdapter);
+    private getWithExpiry;
+    private setWithExpiry;
+    private getSessionId;
+    private pushMetric;
+    trackNavigationPath(path: string): void;
+    initNavigationTracking(): void;
+    fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;
+    isAuthenticated(): boolean;
+    getSessionUser(): any;
+    goToPortal(): Promise<void>;
+    logout(): Promise<void>;
+    login(): Promise<void>;
+    handleRedirect(): Promise<null | undefined>;
+}
+export { AuditAuthWeb };

package/dist/sdk.js

@@ -0,0 +1,164 @@
+import { authorizeCode, buildAuthUrl, buildPortalUrl, CORE_SETTINGS, refreshTokens, revokeSession } from "@auditauth/core";
+class AuditAuthWeb {
+    constructor(config, storage) {
+        this.config = config;
+        this.storage = storage;
+    }
+    getWithExpiry(key) {
+        const itemStr = this.storage.get(key);
+        if (!itemStr)
+            return null;
+        const item = JSON.parse(itemStr);
+        if (Date.now() > item.expiresAt) {
+            this.storage.remove(key);
+            return null;
+        }
+        return item.value;
+    }
+    setWithExpiry(key, value, ttlSeconds) {
+        const now = Date.now();
+        const item = {
+            value,
+            expiresAt: now + ttlSeconds * 1000,
+        };
+        this.storage.set(key, JSON.stringify(item));
+    }
+    getSessionId() {
+        let session_id = this.getWithExpiry(CORE_SETTINGS.storage_keys.session_id);
+        if (!session_id) {
+            session_id = crypto.randomUUID();
+            this.setWithExpiry(CORE_SETTINGS.storage_keys.session_id, session_id, 60 * 5);
+        }
+        return session_id;
+    }
+    pushMetric(metric) {
+        const session_id = this.getSessionId();
+        const body = JSON.stringify({
+            appId: this.config.appId,
+            apiKey: this.config.apiKey,
+            session_id,
+            ...metric,
+        });
+        const url = `${CORE_SETTINGS.domains.api}/metrics`;
+        if (navigator.sendBeacon) {
+            const blob = new Blob([body], { type: 'application/json' });
+            navigator.sendBeacon(url, blob);
+            return;
+        }
+        fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+            keepalive: true,
+        }).catch(() => { });
+    }
+    trackNavigationPath(path) {
+        this.pushMetric({
+            event_type: 'navigation',
+            runtime: 'browser',
+            target: {
+                type: 'page',
+                path: path,
+            },
+        });
+    }
+    initNavigationTracking() {
+        const track = () => {
+            this.pushMetric({
+                event_type: 'navigation',
+                runtime: 'browser',
+                target: {
+                    type: 'page',
+                    path: window.location.pathname,
+                },
+            });
+        };
+        window.addEventListener('popstate', track);
+        const originalPushState = history.pushState;
+        history.pushState = (...args) => {
+            originalPushState.apply(history, args);
+            track();
+        };
+    }
+    async fetch(input, init = {}) {
+        const start = performance.now();
+        let access = this.getWithExpiry(CORE_SETTINGS.storage_keys.access);
+        const doFetch = (token) => fetch(input, {
+            ...init,
+            credentials: 'include',
+            headers: {
+                ...init.headers,
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            },
+        });
+        let res = await doFetch(access || undefined);
+        if (res.status === 401) {
+            const refreshData = await refreshTokens({ client_type: 'browser' });
+            if (!refreshData) {
+                await this.logout();
+                return res;
+            }
+            this.setWithExpiry(CORE_SETTINGS.storage_keys.access, refreshData.access_token, refreshData.access_expires_seconds);
+            res = await doFetch(refreshData.access_token);
+        }
+        this.pushMetric({
+            event_type: 'request',
+            runtime: 'browser',
+            target: {
+                type: 'api',
+                method: init.method || 'GET',
+                path: typeof input === 'string'
+                    ? input
+                    : input instanceof Request
+                        ? input.url
+                        : '',
+                status: res.status,
+                duration_ms: Math.round(performance.now() - start),
+            },
+        });
+        return res;
+    }
+    isAuthenticated() {
+        return !!this.getWithExpiry(CORE_SETTINGS.storage_keys.session);
+    }
+    getSessionUser() {
+        const value = this.getWithExpiry(CORE_SETTINGS.storage_keys.session);
+        return value ? value?.user : null;
+    }
+    async goToPortal() {
+        const access_token = this.getWithExpiry(CORE_SETTINGS.storage_keys.access);
+        if (!access_token)
+            return this.login();
+        const url = await buildPortalUrl({ access_token, redirectUrl: this.config.redirectUrl });
+        window.location.href = url.href;
+    }
+    async logout() {
+        const access_token = this.getWithExpiry(CORE_SETTINGS.storage_keys.access);
+        await revokeSession({ access_token }).catch(() => { });
+        this.storage.remove(CORE_SETTINGS.storage_keys.access);
+        this.storage.remove(CORE_SETTINGS.storage_keys.session);
+        window.location.reload();
+    }
+    async login() {
+        const url = await buildAuthUrl({
+            apiKey: this.config.apiKey,
+            redirectUrl: this.config.redirectUrl,
+        });
+        window.location.href = url.href;
+    }
+    async handleRedirect() {
+        const url = new URL(window.location.href);
+        const code = url.searchParams.get('code');
+        try {
+            const { data } = await authorizeCode({ code, client_type: 'browser' });
+            this.setWithExpiry(CORE_SETTINGS.storage_keys.access, data.access_token, data.access_expires_seconds);
+            this.setWithExpiry(CORE_SETTINGS.storage_keys.session, { user: data.user }, data.access_expires_seconds);
+            url.searchParams.delete('code');
+            window.history.replaceState({}, document.title, url.pathname + url.search);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export { AuditAuthWeb };

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+type StorageAdapter = {
+    get: (name: string) => string | null;
+    set: (name: string, value: string) => void;
+    remove: (name: string) => void;
+};
+export type { StorageAdapter };

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@auditauth/web",
+  "version": "0.2.0-beta.1",
+  "description": "AuditAuth Web SDK (framework-agnostic)",
+  "license": "MIT",
+  "author": "Nimibyte",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nimibyte/auditauth-sdk.git"
+  },
+  "homepage": "https://docs.auditauth.com",
+  "bugs": {
+    "url": "https://github.com/nimibyte/auditauth-sdk/issues"
+  },
+  "keywords": [
+    "authentication",
+    "auth",
+    "oauth",
+    "identity",
+    "jwt",
+    "security",
+    "auditauth"
+  ],
+  "module": "dist/index.js",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@auditauth/core": "^0.2.0-beta.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}