@douvery/auth 0.2.1 → 0.3.0

package/README.md

@@ -29,6 +29,9 @@
 - 📡 **Event System** - Subscribe to auth events (login, logout, token refresh)
 - 🌐 **SSR Compatible** - Works with server-side rendering
 - 🪶 **Lightweight** - ~23KB core, framework adapters add minimal overhead
+- 🧭 **Auth Navigation** - Built-in helpers for all auth flows (register, recover, verify, switch account, etc.)
+- 🔗 **URL Builders** - Generate auth URLs for `<a>` tags without programmatic redirect
+- 🔑 **Token Revocation** - Revoke access/refresh tokens via RFC 7009
 
 ---
 
@@ -197,6 +200,31 @@ fetch('/api/protected', {
 
 // 7. Logout
 await auth.logout();
+
+// 8. Navigation helpers — redirect to any auth flow
+auth.selectAccount({ returnTo: '/dashboard' });
+auth.addAccount({ loginHint: 'other@email.com' });
+auth.register({ email: 'new@email.com' });
+auth.recoverAccount({ email: 'user@email.com' });
+auth.verifyAccount();
+auth.upgradeAccount();
+auth.setupPasskey();
+auth.setupAddress();
+
+// 9. URL builders (don't redirect, useful for <a> tags)
+const url = auth.buildSelectAccountUrl({ returnTo: '/home' });
+console.log(url.url);   // "https://auth.douvery.com/select-account?continue=/home"
+url.redirect();          // Navigate to the URL
+url.open();              // Open in new tab
+
+// 10. Revoke a token
+await auth.revokeToken();
+await auth.revokeToken({ tokenTypeHint: 'refresh_token' });
+
+// 11. Session status helpers
+auth.isSessionExpired();        // true/false
+auth.needsEmailVerification();  // true/false
+auth.isGuestAccount();          // true/false
 ```
 
 ---
@@ -280,6 +308,106 @@ await auth.logout({
 });
 ```
 
+### Navigation Options
+
+All navigation methods accept a common base of options:
+
+```typescript
+interface AuthNavigationOptions {
+  returnTo?: string;      // URL to return to after the action
+  clientId?: string;      // OAuth client_id for branded experiences
+  openInNewTab?: boolean; // Open in new tab instead of redirect
+}
+```
+
+```typescript
+// Select / switch account
+auth.selectAccount({
+  returnTo: '/dashboard',
+  loginHint: 'user@email.com', // Pre-select a specific account
+});
+
+// Add another account (multi-session)
+auth.addAccount({
+  loginHint: 'another@email.com',
+});
+
+// Register a new account
+auth.register({
+  email: 'new@email.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  uiLocales: 'es',
+});
+
+// Recover account (forgot password)
+auth.recoverAccount({
+  email: 'user@email.com',
+});
+
+// Verify account (email verification)
+auth.verifyAccount({
+  email: 'user@email.com',
+});
+
+// Upgrade guest account to full account
+auth.upgradeAccount({
+  scopes: ['profile', 'email'],
+});
+
+// Setup passkey
+auth.setupPasskey({ returnTo: '/settings' });
+
+// Setup address
+auth.setupAddress({ returnTo: '/checkout' });
+```
+
+### URL Builders
+
+Every navigation method has a corresponding `build*Url()` method that returns an `AuthUrl` object without redirecting. Useful for `<a>` tags or custom navigation logic:
+
+```typescript
+const url = auth.buildRegisterUrl({ email: 'hint@test.com' });
+
+url.url;        // "https://auth.douvery.com/register?email=hint%40test.com"
+url.redirect(); // window.location.href = url
+url.open();     // window.open(url, '_blank')
+```
+
+| Builder | Path |
+|---|---|
+| `buildLoginUrl()` | `/login` |
+| `buildLogoutUrl()` | `/logout` |
+| `buildSelectAccountUrl()` | `/select-account` |
+| `buildAddAccountUrl()` | `/login?add_account=true` |
+| `buildRegisterUrl()` | `/register` |
+| `buildRecoverAccountUrl()` | `/recover-account` |
+| `buildVerifyAccountUrl()` | `/verify-account` |
+| `buildUpgradeAccountUrl()` | `/upgrade-account` |
+| `buildSetupPasskeyUrl()` | `/setup-passkey` |
+| `buildSetupAddressUrl()` | `/setup-address` |
+
+### Token Revocation
+
+```typescript
+// Revoke current access token
+await auth.revokeToken();
+
+// Revoke a specific token
+await auth.revokeToken({
+  token: 'specific-token-value',
+  tokenTypeHint: 'refresh_token',
+});
+```
+
+### Session Status Helpers
+
+```typescript
+auth.isSessionExpired();        // true if access token is expired
+auth.needsEmailVerification();  // true if email is not verified
+auth.isGuestAccount();          // true if account type is guest
+```
+
 ### Auth State
 
 ```typescript
@@ -330,7 +458,47 @@ type AuthEvent =
 | `useUser()` | Current user or null |
 | `useIsAuthenticated()` | Boolean authentication status |
 | `useAccessToken()` | `{ accessToken, getAccessToken }` |
-| `useAuthActions()` | `{ login, logout, isLoading }` |
+| `useAuthActions()` | All auth actions (see below) |
+| `useAuthUrls()` | URL builders for all auth pages |
+| `useSessionStatus()` | `{ isExpired, needsVerification, isGuest }` |
+
+#### `useAuthActions()` — Full list
+
+```tsx
+const {
+  login,           // (options?: LoginOptions) => Promise<void>
+  logout,          // (options?: LogoutOptions) => Promise<void>
+  selectAccount,   // (options?: SelectAccountOptions) => void
+  addAccount,      // (options?: AddAccountOptions) => void
+  register,        // (options?: RegisterOptions) => void
+  recoverAccount,  // (options?: RecoverAccountOptions) => void
+  verifyAccount,   // (options?: VerifyAccountOptions) => void
+  upgradeAccount,  // (options?: UpgradeAccountOptions) => void
+  setupPasskey,    // (options?: SetupPasskeyOptions) => void
+  setupAddress,    // (options?: SetupAddressOptions) => void
+  revokeToken,     // (options?: RevokeTokenOptions) => Promise<void>
+  isLoading,       // boolean
+} = useAuthActions();
+```
+
+#### `useAuthUrls()` — URL builders for links
+
+```tsx
+const urls = useAuthUrls();
+
+<a href={urls.registerUrl().url}>Create account</a>
+<a href={urls.recoverAccountUrl({ email: user.email }).url}>Forgot password?</a>
+<a href={urls.selectAccountUrl().url}>Switch account</a>
+```
+
+#### `useSessionStatus()` — Reactive status
+
+```tsx
+const { isExpired, needsVerification, isGuest } = useSessionStatus();
+
+{needsVerification && <Banner>Please verify your email</Banner>}
+{isGuest && <button onClick={() => upgradeAccount()}>Upgrade account</button>}
+```
 
 ### DouveryAuthProvider Props
 
@@ -354,7 +522,36 @@ interface DouveryAuthProviderProps {
 | `useDouveryAuth()` | Context | Full context with signals and client |
 | `useUser()` | `Signal<User \| null>` | Reactive user signal |
 | `useIsAuthenticated()` | `Signal<boolean>` | Reactive auth status |
-| `useAuthActions()` | `{ login, logout, isLoading }` | Auth actions |
+| `useAuthActions()` | All actions + `isLoading` | Auth actions (same as React) |
+| `useAuthUrls()` | URL builders | Build URLs for auth pages |
+| `useSessionStatus()` | `{ isExpired, needsVerification, isGuest }` | Reactive session signals |
+
+#### Qwik example with navigation
+
+```tsx
+import { component$ } from '@builder.io/qwik';
+import { useAuthActions, useSessionStatus } from '@douvery/auth/qwik';
+
+export const AccountMenu = component$(() => {
+  const { selectAccount, addAccount, recoverAccount, upgradeAccount } = useAuthActions();
+  const { isGuest, needsVerification } = useSessionStatus();
+
+  return (
+    <div>
+      <button onClick$={() => selectAccount({ returnTo: window.location.href })}>
+        Switch account
+      </button>
+      <button onClick$={() => addAccount()}>Add account</button>
+      {isGuest.value && (
+        <button onClick$={() => upgradeAccount()}>Upgrade account</button>
+      )}
+      {needsVerification.value && (
+        <button onClick$={() => verifyAccount()}>Verify email</button>
+      )}
+    </div>
+  );
+});
+```
 
 ---
 

package/dist/index.d.ts

@@ -207,6 +207,64 @@ interface LogoutOptions {
     /** Only clear local session, don't redirect @default false */
     localOnly?: boolean;
 }
+/** Base options for all auth navigation redirects */
+interface AuthNavigationOptions {
+    /** URL to return to after the action completes */
+    returnTo?: string;
+    /** OAuth client_id for branded experiences */
+    clientId?: string;
+    /** Open in a new tab/window instead of redirecting */
+    openInNewTab?: boolean;
+}
+interface SelectAccountOptions extends AuthNavigationOptions {
+    /** Pre-select a specific email/account */
+    loginHint?: string;
+}
+interface RegisterOptions extends AuthNavigationOptions {
+    /** Pre-fill email on register form */
+    email?: string;
+    /** Pre-fill first name */
+    firstName?: string;
+    /** Pre-fill last name */
+    lastName?: string;
+    /** UI locale preference */
+    uiLocales?: string;
+}
+interface RecoverAccountOptions extends AuthNavigationOptions {
+    /** Pre-fill email for recovery */
+    email?: string;
+}
+interface VerifyAccountOptions extends AuthNavigationOptions {
+    /** Email to verify */
+    email?: string;
+}
+interface UpgradeAccountOptions extends AuthNavigationOptions {
+    /** Scopes to request on upgrade */
+    scopes?: string[];
+}
+interface SetupPasskeyOptions extends AuthNavigationOptions {
+}
+interface SetupAddressOptions extends AuthNavigationOptions {
+}
+interface AddAccountOptions extends AuthNavigationOptions {
+    /** Pre-fill email hint for the new account */
+    loginHint?: string;
+}
+interface RevokeTokenOptions {
+    /** Specific token to revoke. If not provided, revokes current access token */
+    token?: string;
+    /** Token type hint: "access_token" or "refresh_token" */
+    tokenTypeHint?: "access_token" | "refresh_token";
+}
+/** Result of URL builder methods (non-redirecting) */
+interface AuthUrl {
+    /** The full URL */
+    url: string;
+    /** Open the URL via redirect */
+    redirect: () => void;
+    /** Open the URL in a new tab */
+    open: () => Window | null;
+}
 
 /**
  * @douvery/auth - Auth Client
@@ -236,7 +294,55 @@ declare class DouveryAuthClient {
     refreshTokens(): Promise<TokenInfo>;
     /** Get current access token (auto-refreshes if needed) */
     getAccessToken(): Promise<string | null>;
+    /** Redirect to select/switch account */
+    selectAccount(options?: SelectAccountOptions): void;
+    /** Build select-account URL without redirecting */
+    buildSelectAccountUrl(options?: SelectAccountOptions): AuthUrl;
+    /** Redirect to add another account (multi-session) */
+    addAccount(options?: AddAccountOptions): void;
+    /** Build add-account URL without redirecting */
+    buildAddAccountUrl(options?: AddAccountOptions): AuthUrl;
+    /** Redirect to register a new account */
+    register(options?: RegisterOptions): void;
+    /** Build register URL without redirecting */
+    buildRegisterUrl(options?: RegisterOptions): AuthUrl;
+    /** Redirect to recover account (forgot password) */
+    recoverAccount(options?: RecoverAccountOptions): void;
+    /** Build recover-account URL without redirecting */
+    buildRecoverAccountUrl(options?: RecoverAccountOptions): AuthUrl;
+    /** Redirect to verify account (email verification) */
+    verifyAccount(options?: VerifyAccountOptions): void;
+    /** Build verify-account URL without redirecting */
+    buildVerifyAccountUrl(options?: VerifyAccountOptions): AuthUrl;
+    /** Redirect to upgrade account (guest → full account) */
+    upgradeAccount(options?: UpgradeAccountOptions): void;
+    /** Build upgrade-account URL without redirecting */
+    buildUpgradeAccountUrl(options?: UpgradeAccountOptions): AuthUrl;
+    /** Redirect to passkey setup */
+    setupPasskey(options?: SetupPasskeyOptions): void;
+    /** Build setup-passkey URL without redirecting */
+    buildSetupPasskeyUrl(options?: SetupPasskeyOptions): AuthUrl;
+    /** Redirect to address setup */
+    setupAddress(options?: SetupAddressOptions): void;
+    /** Build setup-address URL without redirecting */
+    buildSetupAddressUrl(options?: SetupAddressOptions): AuthUrl;
+    /** Build a login URL without redirecting (useful for links/buttons) */
+    buildLoginUrl(options?: LoginOptions): AuthUrl;
+    /** Build a logout URL without redirecting */
+    buildLogoutUrl(options?: LogoutOptions): AuthUrl;
+    /** Revoke a token (access or refresh) */
+    revokeToken(options?: RevokeTokenOptions): Promise<void>;
+    /** Check if the user's session is expired */
+    isSessionExpired(): boolean;
+    /** Check if user needs email verification */
+    needsEmailVerification(): boolean;
+    /** Check if user is a guest account */
+    isGuestAccount(): boolean;
     private tokenSetToInfo;
+    /** Build an AuthUrl object for a given path and params */
+    private createAuthUrl;
+    /** Navigate to an auth URL, respecting openInNewTab option */
+    private navigate;
     private fetchUser;
     private extractUserFromIdToken;
     private normalizeUser;
@@ -349,4 +455,4 @@ declare class TokenManager {
     clearAll(): Promise<void>;
 }
 
-export { AuthError, type AuthErrorCode, type AuthEvent, type AuthEventHandler, type AuthState, type AuthStatus, type CallbackResult, CookieStorage, type DecodedIdToken, DouveryAuthClient, type DouveryAuthConfig, LocalStorage, type LoginOptions, type LogoutOptions, MemoryStorage, type OIDCDiscovery, type PKCEPair, STORAGE_KEYS, SessionStorage, type StorageKeys, type TokenInfo, TokenManager, type TokenSet, type TokenStorage, type User, base64UrlDecode, base64UrlEncode, createDouveryAuth, createStorage, decodeJWT, generateCodeChallenge, generateCodeVerifier, generateNonce, generatePKCEPair, generateState, getTokenExpiration, isTokenExpired, verifyCodeChallenge };
+export { type AddAccountOptions, AuthError, type AuthErrorCode, type AuthEvent, type AuthEventHandler, type AuthNavigationOptions, type AuthState, type AuthStatus, type AuthUrl, type CallbackResult, CookieStorage, type DecodedIdToken, DouveryAuthClient, type DouveryAuthConfig, LocalStorage, type LoginOptions, type LogoutOptions, MemoryStorage, type OIDCDiscovery, type PKCEPair, type RecoverAccountOptions, type RegisterOptions, type RevokeTokenOptions, STORAGE_KEYS, type SelectAccountOptions, SessionStorage, type SetupAddressOptions, type SetupPasskeyOptions, type StorageKeys, type TokenInfo, TokenManager, type TokenSet, type TokenStorage, type UpgradeAccountOptions, type User, type VerifyAccountOptions, base64UrlDecode, base64UrlEncode, createDouveryAuth, createStorage, decodeJWT, generateCodeChallenge, generateCodeVerifier, generateNonce, generatePKCEPair, generateState, getTokenExpiration, isTokenExpired, verifyCodeChallenge };

package/dist/index.js

@@ -636,6 +636,171 @@ var DouveryAuthClient = class {
     }
     return tokens.accessToken;
   }
+  // ============================================
+  // Navigation Methods
+  // ============================================
+  /** Redirect to select/switch account */
+  selectAccount(options = {}) {
+    const url = this.buildSelectAccountUrl(options);
+    this.navigate(url, options);
+  }
+  /** Build select-account URL without redirecting */
+  buildSelectAccountUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.clientId) params.set("client_id", options.clientId);
+    if (options.loginHint) params.set("login_hint", options.loginHint);
+    return this.createAuthUrl("/select-account", params);
+  }
+  /** Redirect to add another account (multi-session) */
+  addAccount(options = {}) {
+    const url = this.buildAddAccountUrl(options);
+    this.navigate(url, options);
+  }
+  /** Build add-account URL without redirecting */
+  buildAddAccountUrl(options = {}) {
+    const params = new URLSearchParams({ add_account: "true" });
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.clientId) params.set("client_id", options.clientId);
+    if (options.loginHint) params.set("login_hint", options.loginHint);
+    return this.createAuthUrl("/login", params);
+  }
+  /** Redirect to register a new account */
+  register(options = {}) {
+    const url = this.buildRegisterUrl(options);
+    this.navigate(url, options);
+  }
+  /** Build register URL without redirecting */
+  buildRegisterUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.clientId) params.set("client_id", options.clientId);
+    if (options.email) params.set("email", options.email);
+    if (options.firstName) params.set("first_name", options.firstName);
+    if (options.lastName) params.set("last_name", options.lastName);
+    if (options.uiLocales) params.set("ui_locales", options.uiLocales);
+    return this.createAuthUrl("/register", params);
+  }
+  /** Redirect to recover account (forgot password) */
+  recoverAccount(options = {}) {
+    const url = this.buildRecoverAccountUrl(options);
+    this.navigate(url, options);
+  }
+  /** Build recover-account URL without redirecting */
+  buildRecoverAccountUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.clientId) params.set("client_id", options.clientId);
+    if (options.email) params.set("email", options.email);
+    return this.createAuthUrl("/recover-account", params);
+  }
+  /** Redirect to verify account (email verification) */
+  verifyAccount(options = {}) {
+    const url = this.buildVerifyAccountUrl(options);
+    this.navigate(url, options);
+  }
+  /** Build verify-account URL without redirecting */
+  buildVerifyAccountUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.clientId) params.set("client_id", options.clientId);
+    if (options.email) params.set("email", options.email);
+    return this.createAuthUrl("/verify-account", params);
+  }
+  /** Redirect to upgrade account (guest → full account) */
+  upgradeAccount(options = {}) {
+    const url = this.buildUpgradeAccountUrl(options);
+    this.navigate(url, options);
+  }
+  /** Build upgrade-account URL without redirecting */
+  buildUpgradeAccountUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.clientId) params.set("client_id", options.clientId);
+    if (options.scopes?.length) params.set("scope", options.scopes.join(" "));
+    return this.createAuthUrl("/upgrade-account", params);
+  }
+  /** Redirect to passkey setup */
+  setupPasskey(options = {}) {
+    const url = this.buildSetupPasskeyUrl(options);
+    this.navigate(url, options);
+  }
+  /** Build setup-passkey URL without redirecting */
+  buildSetupPasskeyUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.clientId) params.set("client_id", options.clientId);
+    return this.createAuthUrl("/setup-passkey", params);
+  }
+  /** Redirect to address setup */
+  setupAddress(options = {}) {
+    const url = this.buildSetupAddressUrl(options);
+    this.navigate(url, options);
+  }
+  /** Build setup-address URL without redirecting */
+  buildSetupAddressUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.clientId) params.set("client_id", options.clientId);
+    return this.createAuthUrl("/setup-address", params);
+  }
+  /** Build a login URL without redirecting (useful for links/buttons) */
+  buildLoginUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    if (options.loginHint) params.set("email", options.loginHint);
+    if (options.prompt) params.set("prompt", options.prompt);
+    if (options.uiLocales) params.set("ui_locales", options.uiLocales);
+    return this.createAuthUrl("/login", params);
+  }
+  /** Build a logout URL without redirecting */
+  buildLogoutUrl(options = {}) {
+    const params = new URLSearchParams();
+    if (options.returnTo) params.set("continue", options.returnTo);
+    return this.createAuthUrl("/logout", params);
+  }
+  /** Revoke a token (access or refresh) */
+  async revokeToken(options = {}) {
+    this.log("Revoking token...");
+    const token = options.token ?? (await this.tokenManager.getTokens())?.accessToken;
+    if (!token) {
+      throw new AuthError("invalid_token", "No token to revoke");
+    }
+    const revokeUrl = `${this.config.issuer}/oauth/revoke`;
+    const body = new URLSearchParams({
+      token,
+      client_id: this.config.clientId
+    });
+    if (options.tokenTypeHint) {
+      body.set("token_type_hint", options.tokenTypeHint);
+    }
+    const response = await fetch(revokeUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new AuthError(
+        error.error ?? "server_error",
+        error.error_description ?? "Token revocation failed"
+      );
+    }
+    this.log("Token revoked successfully");
+  }
+  /** Check if the user's session is expired */
+  isSessionExpired() {
+    if (!this.state.tokens) return true;
+    return isTokenExpired(this.state.tokens.accessToken);
+  }
+  /** Check if user needs email verification */
+  needsEmailVerification() {
+    return this.state.user?.emailVerified === false;
+  }
+  /** Check if user is a guest account */
+  isGuestAccount() {
+    return this.state.user?.accountType === "guest";
+  }
   tokenSetToInfo(tokenSet) {
     return {
       accessToken: tokenSet.access_token,
@@ -646,6 +811,28 @@ var DouveryAuthClient = class {
       scope: tokenSet.scope?.split(" ") ?? []
     };
   }
+  /** Build an AuthUrl object for a given path and params */
+  createAuthUrl(path, params) {
+    const query = params.toString();
+    const url = `${this.config.issuer}${path}${query ? `?${query}` : ""}`;
+    return {
+      url,
+      redirect: () => {
+        window.location.href = url;
+      },
+      open: () => {
+        return window.open(url, "_blank");
+      }
+    };
+  }
+  /** Navigate to an auth URL, respecting openInNewTab option */
+  navigate(authUrl, options) {
+    if (options.openInNewTab) {
+      authUrl.open();
+    } else {
+      authUrl.redirect();
+    }
+  }
   async fetchUser(accessToken) {
     const discovery = await this.getDiscovery();
     const response = await fetch(discovery.userinfo_endpoint, {