@nexauthxyz/browser 0.1.2

package/dist/storage.js

@@ -0,0 +1,95 @@
+import { NexAuthError } from './errors.js';
+function normalizeKeyPart(value, name) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new NexAuthError('invalid_configuration', `${name} cannot be empty.`);
+    }
+    return normalized.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+export function getDefaultBrowserStorage() {
+    if (typeof window === 'undefined' ||
+        typeof window.sessionStorage === 'undefined') {
+        throw new NexAuthError('storage_error', 'Browser session storage is unavailable.');
+    }
+    return window.sessionStorage;
+}
+export class NexAuthStorageManager {
+    storage;
+    namespace;
+    constructor(storage, prefix, clientId) {
+        this.storage = storage;
+        const normalizedPrefix = normalizeKeyPart(prefix, 'Storage prefix');
+        const normalizedClientId = normalizeKeyPart(clientId, 'Client ID');
+        this.namespace = `${normalizedPrefix}:${normalizedClientId}`;
+    }
+    get(entry) {
+        const key = this.getKey(entry);
+        let raw;
+        try {
+            raw = this.storage.getItem(key);
+        }
+        catch (error) {
+            throw new NexAuthError('storage_error', 'Unable to read NexAuth browser storage.', {
+                cause: error,
+            });
+        }
+        if (raw === null) {
+            return null;
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            /*
+             * Corrupted browser state must not repeatedly break authentication.
+             */
+            this.remove(entry);
+            throw new NexAuthError('storage_error', 'Stored NexAuth browser state is invalid.', {
+                cause: error,
+            });
+        }
+    }
+    set(entry, value) {
+        const key = this.getKey(entry);
+        let serialized;
+        try {
+            serialized = JSON.stringify(value);
+        }
+        catch (error) {
+            throw new NexAuthError('storage_error', 'Unable to serialize NexAuth browser state.', {
+                cause: error,
+            });
+        }
+        try {
+            this.storage.setItem(key, serialized);
+        }
+        catch (error) {
+            throw new NexAuthError('storage_error', 'Unable to save NexAuth browser state.', {
+                cause: error,
+            });
+        }
+    }
+    remove(entry) {
+        try {
+            this.storage.removeItem(this.getKey(entry));
+        }
+        catch (error) {
+            throw new NexAuthError('storage_error', 'Unable to remove NexAuth browser state.', {
+                cause: error,
+            });
+        }
+    }
+    clear() {
+        /*
+         * Remove only this NexAuth client's entries.
+         * Never call storage.clear(), because it would delete unrelated
+         * application data.
+         */
+        this.remove('session');
+        this.remove('transaction');
+    }
+    getKey(entry) {
+        return `${this.namespace}:${entry}`;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,143 @@
+export interface OpenIdConfiguration {
+    readonly issuer: string;
+    readonly authorization_endpoint: string;
+    readonly token_endpoint: string;
+    readonly userinfo_endpoint: string;
+    readonly jwks_uri: string;
+    readonly end_session_endpoint?: string;
+    readonly response_types_supported: readonly string[];
+    readonly grant_types_supported: readonly string[];
+    readonly subject_types_supported: readonly string[];
+    readonly id_token_signing_alg_values_supported: readonly string[];
+    readonly scopes_supported: readonly string[];
+    readonly claims_supported?: readonly string[];
+    readonly code_challenge_methods_supported: readonly string[];
+    readonly token_endpoint_auth_methods_supported: readonly string[];
+}
+export interface NexAuthUser {
+    readonly sub: string;
+    readonly email?: string;
+    readonly email_verified?: boolean;
+    readonly name?: string;
+    readonly picture?: string;
+    readonly organization_id?: string;
+    readonly organization_role?: string;
+    readonly permissions?: readonly string[];
+    readonly [claim: string]: unknown;
+}
+export interface OAuthTokenResponse {
+    readonly access_token: string;
+    readonly token_type: string;
+    readonly expires_in: number;
+    readonly scope?: string;
+    readonly id_token?: string;
+    readonly refresh_token?: string;
+}
+export interface NexAuthIdTokenClaims {
+    readonly iss: string;
+    readonly sub: string;
+    readonly aud: string | readonly string[];
+    readonly exp: number;
+    readonly iat: number;
+    readonly nonce: string;
+    readonly azp?: string;
+    readonly email?: string;
+    readonly email_verified?: boolean;
+    readonly name?: string;
+    readonly picture?: string;
+    readonly [claim: string]: unknown;
+}
+export interface NexAuthSession {
+    readonly accessToken: string;
+    readonly tokenType: 'Bearer';
+    readonly expiresAt: number;
+    readonly scope?: string;
+    readonly idToken?: string;
+    readonly refreshToken?: string;
+    readonly user: NexAuthUser;
+    readonly idTokenClaims?: NexAuthIdTokenClaims;
+}
+export interface AuthorizationTransaction {
+    readonly state: string;
+    readonly nonce: string;
+    readonly codeVerifier: string;
+    readonly redirectUri: string;
+    readonly returnTo?: string;
+    readonly createdAt: number;
+}
+export interface NexAuthStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface NexAuthBrowserClientOptions {
+    /**
+     * NexAuth issuer. It must exactly match the issuer returned by discovery.
+     *
+     * Example: https://api.nexauth.xyz
+     */
+    readonly issuer: string;
+    /**
+     * Public application client ID generated by NexAuth.
+     */
+    readonly clientId: string;
+    /**
+     * Registered callback URI.
+     *
+     * Defaults to `${window.location.origin}/auth/callback`.
+     */
+    readonly redirectUri?: string;
+    /**
+     * Requested OIDC scopes.
+     *
+     * Defaults to `openid profile email`.
+     */
+    readonly scope?: string;
+    /**
+     * Optional storage implementation.
+     *
+     * Defaults to browser sessionStorage.
+     */
+    readonly storage?: NexAuthStorage;
+    /**
+     * Optional fetch implementation, primarily for testing.
+     */
+    readonly fetch?: typeof globalThis.fetch;
+    /**
+     * Storage-key namespace.
+     *
+     * Defaults to `nexauth`.
+     */
+    readonly storageKeyPrefix?: string;
+}
+export interface LoginOptions {
+    /**
+     * Application route restored after callback processing.
+     *
+     * This is stored locally and is never accepted as a server redirect URI.
+     */
+    readonly returnTo?: string;
+    /**
+     * Optional OIDC prompt value.
+     */
+    readonly prompt?: 'none' | 'login' | 'consent' | 'select_account';
+    /**
+     * Optional additional scopes for this authorization request.
+     */
+    readonly additionalScopes?: readonly string[];
+}
+export interface AuthorizationCallbackInput {
+    readonly url?: string;
+}
+export interface AuthorizationCallbackResult {
+    readonly session: NexAuthSession;
+    readonly returnTo?: string;
+}
+export interface LogoutOptions {
+    /**
+     * If true, only local SDK state is cleared.
+     */
+    readonly localOnly?: boolean;
+}
+export type AuthenticationStatus = 'loading' | 'authenticated' | 'unauthenticated' | 'error';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@nexauthxyz/browser",
+  "version": "0.1.2",
+  "description": "Official browser SDK for NexAuth using OpenID Connect Authorization Code with PKCE.",
+  "author": {
+    "name": "nexauthteam",
+    "url": "https://nexauth.xyz"
+  },
+  "license": "MIT",
+  "homepage": "https://nexauth.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danialafridi1/nexauth.git",
+    "directory": "packages/browser-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/danialafridi1/nexauth/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --config vitest.config.ts",
+    "prepack": "npm run clean && npm run build",
+    "prepublishOnly": "npm run typecheck && npm run test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "nexauth",
+    "authentication",
+    "authorization",
+    "oauth2",
+    "oidc",
+    "openid-connect",
+    "pkce",
+    "browser",
+    "typescript",
+    "javascript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jose": "^6.2.12"
+  }
+}

package/readme.md

@@ -0,0 +1,282 @@
+# `@nexauthxyz/browser`
+
+Official framework-independent browser SDK for NexAuth. It implements OpenID Connect Authorization Code Flow with PKCE and can be used by React, Vue, Svelte, Angular, or plain browser applications.
+
+## What this package does
+
+- Loads NexAuth endpoints from OIDC discovery.
+- Generates cryptographically secure PKCE, `state`, and `nonce` values.
+- Redirects the browser to the NexAuth authorization endpoint.
+- Exchanges an authorization code for tokens.
+- Validates the returned ID token using the provider JWKS.
+- Validates issuer, audience, signature, expiry, algorithm, and nonce.
+- Loads the signed-in user from the UserInfo endpoint.
+- Stores the authorization transaction and authenticated session in browser `sessionStorage` by default.
+- Clears local authentication state and supports provider logout when advertised by discovery.
+
+The SDK does not contain administrative credentials, a client secret, signing keys, or subscription enforcement logic.
+
+## Requirements
+
+- A modern browser with Web Crypto, `fetch`, `URL`, and Web Storage support.
+- A NexAuth application with an active subscription/entitlement.
+- A public NexAuth client ID.
+- An exact registered redirect URI.
+- A registered browser origin when required by the NexAuth server.
+- NexAuth discovery, token, UserInfo, and JWKS endpoints available through HTTPS in production.
+
+## Installation
+
+```bash
+npm install @nexauthxyz/browser
+```
+
+## Dependencies
+
+| Package             | Relationship                | Purpose                                                                                                   |
+| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `jose`              | Runtime dependency          | Validates RS256 ID tokens and resolves keys from JWKS.                                                    |
+| NexAuth OIDC server | External service dependency | Performs authorization, token issuance, UserInfo, logout, entitlement checks, and application validation. |
+
+This package has no dependency on React or another UI framework.
+
+## Basic usage
+
+```ts
+import { NexAuthBrowserClient } from '@nexauthxyz/browser';
+
+const nexAuth = new NexAuthBrowserClient({
+  issuer: 'https://api.nexauth.xyz',
+  clientId: 'nxa_your_public_client_id',
+  redirectUri: `${window.location.origin}/auth/callback`,
+  scope: 'openid profile email',
+});
+```
+
+The issuer must exactly match the `issuer` returned by:
+
+```text
+https://api.nexauth.xyz/.well-known/openid-configuration
+```
+
+Do not use `https://auth.nexauth.xyz` as the issuer unless that value is also the discovery document issuer.
+
+## Start login
+
+```ts
+await nexAuth.login({
+  returnTo: '/dashboard',
+});
+```
+
+The SDK creates and stores PKCE and anti-forgery values before redirecting the browser. `returnTo` is local application state; it is not sent as an OAuth redirect URI.
+
+Optional login values:
+
+```ts
+await nexAuth.login({
+  returnTo: '/orders',
+  prompt: 'login',
+  additionalScopes: ['custom.read'],
+});
+```
+
+## Handle the callback
+
+Register the exact callback URI in NexAuth, for example:
+
+```text
+https://shop.example.com/auth/callback
+```
+
+Then process the callback:
+
+```ts
+const result = await nexAuth.handleCallback();
+
+console.log(result.session.user);
+console.log(result.returnTo);
+
+window.history.replaceState({}, '', result.returnTo ?? '/');
+```
+
+You may supply a URL explicitly for testing or custom routing:
+
+```ts
+const result = await nexAuth.handleCallback({
+  url: window.location.href,
+});
+```
+
+## Read the current session
+
+```ts
+const session = nexAuth.getSession();
+
+if (session) {
+  console.log(session.user);
+  console.log(session.accessToken);
+  console.log(new Date(session.expiresAt));
+}
+```
+
+An expired session is not returned as authenticated.
+
+## Call a protected API
+
+```ts
+const session = nexAuth.getSession();
+
+if (!session) {
+  throw new Error('Authentication is required.');
+}
+
+const response = await fetch('https://api.example.com/orders', {
+  headers: {
+    Authorization: `${session.tokenType} ${session.accessToken}`,
+  },
+});
+```
+
+The resource server must validate the access token signature, issuer, audience/client, expiry, and required permissions. A browser session alone is not authorization for a protected backend resource.
+
+## Logout
+
+```ts
+await nexAuth.logout();
+```
+
+Local-only logout:
+
+```ts
+await nexAuth.logout({ localOnly: true });
+```
+
+You can also synchronously remove local SDK state:
+
+```ts
+nexAuth.clearLocalSession();
+```
+
+## Configuration
+
+| Option             | Required | Default                  | Description                                                         |
+| ------------------ | -------- | ------------------------ | ------------------------------------------------------------------- |
+| `issuer`           | Yes      | —                        | NexAuth OIDC issuer, without a trailing slash.                      |
+| `clientId`         | Yes      | —                        | Public application identifier issued by NexAuth.                    |
+| `redirectUri`      | No       | `<origin>/auth/callback` | Exact registered callback URI.                                      |
+| `scope`            | No       | `openid profile email`   | Space-separated requested scopes.                                   |
+| `storage`          | No       | `window.sessionStorage`  | Custom storage implementing `getItem`, `setItem`, and `removeItem`. |
+| `fetch`            | No       | `globalThis.fetch`       | Custom fetch implementation, mainly useful for testing.             |
+| `storageKeyPrefix` | No       | `nexauth`                | Namespace used for SDK storage keys.                                |
+
+## Error handling
+
+```ts
+import { isNexAuthError } from '@nexauthxyz/browser';
+
+try {
+  await nexAuth.handleCallback();
+} catch (error: unknown) {
+  if (isNexAuthError(error)) {
+    console.error(error.code, error.message);
+    console.error('Support reference:', error.requestId);
+  }
+}
+```
+
+Important error codes include:
+
+- `invalid_configuration`
+- `discovery_failed`
+- `invalid_discovery_document`
+- `login_failed`
+- `authorization_error`
+- `invalid_state`
+- `missing_authorization_code`
+- `missing_pkce_transaction`
+- `token_exchange_failed`
+- `invalid_token_response`
+- `id_token_validation_failed`
+- `userinfo_failed`
+- `logout_failed`
+- `network_error`
+- `storage_error`
+
+Display `requestId` as a support reference where available. NexAuth administrators can use it to locate the matching server audit event.
+
+## Security model
+
+`clientId`, issuer, redirect URI, discovery metadata, and JWKS are public information. Never place these values in frontend code:
+
+- Client secrets
+- JWT private keys
+- Database or Redis credentials
+- Administrative API tokens
+- Payment-provider secrets
+- Server-to-server credentials
+
+Publishing this SDK publicly does not grant access to the NexAuth service. The NexAuth backend must enforce application status, subscription entitlement, exact redirect URI matching, allowed origin checks, PKCE S256, authorization-code ownership and expiry, single use, membership, and permissions.
+
+## Package relationship
+
+```text
+Customer application
+  └─ @nexauthxyz/react (optional React integration)
+       └─ @nexauthxyz/browser
+            └─ jose
+                 └─ NexAuth OIDC endpoints
+```
+
+Use this package directly for framework-independent applications. React applications should normally use `@nexauthxyz/react`, which wraps this client.
+
+## Current session-renewal behavior
+
+The SDK detects expired sessions but does not silently renew them unless a secure refresh-token flow is implemented and enabled by the NexAuth backend. Do not simulate refresh by extending browser expiry timestamps. Token renewal must be backed by a real server-side `refresh_token` grant with rotation and replay protection.
+
+## Troubleshooting
+
+### Redirect URI is not registered
+
+Register the full URI, including scheme, hostname, port, path, and trailing-slash behavior. These are different values:
+
+```text
+http://localhost:5173
+http://localhost:5173/auth/callback
+```
+
+### Origin is not registered
+
+Register only the origin where NexAuth expects an allowed origin:
+
+```text
+http://localhost:5173
+```
+
+Do not include `/auth/callback` in an allowed-origin record.
+
+### Issuer mismatch
+
+The configured issuer must exactly match discovery and token `iss` claims. Avoid mixing local and production issuers.
+
+### Application has no active plan
+
+This is a backend entitlement decision. Activate an eligible organization subscription; changing frontend code or the public client ID cannot bypass it.
+
+## Publishing
+
+Build and inspect the package before publishing:
+
+```bash
+npm run test --workspace @nexauthxyz/browser
+npm run typecheck --workspace @nexauthxyz/browser
+npm run build --workspace @nexauthxyz/browser
+npm pack --workspace @nexauthxyz/browser --dry-run
+npm publish --workspace @nexauthxyz/browser --access public
+```
+
+Publish `@nexauthxyz/browser` before publishing a version of `@nexauthxyz/react` that depends on it.
+
+## License
+
+MIT