@docyrus/app-auth-ui 0.0.1

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@docyrus/app-auth-ui",
+  "version": "0.0.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Docyrus/docyrus-devkit.git",
+    "directory": "packages/app-auth-ui"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "25.2.2",
+    "@types/react": "19.2.13",
+    "react": "19.2.4",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "@docyrus/api-client": "0.0.7"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 | >=19.0.0",
+    "@docyrus/api-client": ">=0.0.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "format": "eslint src --fix",
+    "typecheck": "eslint src && tsc --noEmit",
+    "deploy": "pnpm run build && pnpm publish --access public"
+  }
+}

package/src/components/docyrus-auth-provider.tsx

@@ -0,0 +1,95 @@
+import {
+  createContext,
+  useEffect,
+  useRef,
+  useState,
+  useMemo,
+  type ReactNode
+} from 'react';
+
+import { type OAuth2Tokens, type RestApiClient } from '@docyrus/api-client';
+
+import {
+  type AuthStatus,
+  type AuthMode,
+  type DocyrusAuthContextValue,
+  type DocyrusAuthConfig
+} from '../types';
+
+import { AuthManager } from '../core/auth-manager';
+
+export const DocyrusAuthContext = createContext<DocyrusAuthContextValue | null>(null);
+
+export interface DocyrusAuthProviderProps extends DocyrusAuthConfig {
+  children: ReactNode;
+}
+
+export function DocyrusAuthProvider({
+  children,
+  ...config
+}: DocyrusAuthProviderProps) {
+  const [status, setStatus] = useState<AuthStatus>('loading');
+  const [tokens, setTokens] = useState<OAuth2Tokens | null>(null);
+  const [client, setClient] = useState<RestApiClient | null>(null);
+  const [mode, setMode] = useState<AuthMode | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const managerRef = useRef<AuthManager | null>(null);
+
+  useEffect(() => {
+    const manager = new AuthManager(config);
+
+    managerRef.current = manager;
+    setMode(manager.getMode());
+
+    const unsubscribe = manager.subscribe((state) => {
+      setStatus(state.status);
+      setTokens(state.tokens);
+      setError(state.error);
+      setClient(manager.getClient());
+    });
+
+    manager.initialize();
+
+    return () => {
+      unsubscribe();
+      manager.destroy();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const signIn = useMemo(() => {
+    return () => {
+      managerRef.current?.signIn();
+    };
+  }, []);
+
+  const signOut = useMemo(() => {
+    return async () => {
+      await managerRef.current?.signOut();
+    };
+  }, []);
+
+  const value = useMemo<DocyrusAuthContextValue>(() => ({
+    status,
+    mode,
+    client,
+    tokens,
+    signIn,
+    signOut,
+    error
+  }), [
+    status,
+    mode,
+    client,
+    tokens,
+    signIn,
+    signOut,
+    error
+  ]);
+
+  return (
+    <DocyrusAuthContext.Provider value={value}>
+      {children}
+    </DocyrusAuthContext.Provider>
+  );
+}

package/src/components/sign-in-button.tsx

@@ -0,0 +1,62 @@
+import { type ReactNode, type CSSProperties } from 'react';
+
+import { type AuthStatus } from '../types';
+
+import { useDocyrusAuth } from '../hooks/use-docyrus-auth';
+
+export interface SignInButtonProps {
+  /** Custom label. Defaults to "Sign in with Docyrus" */
+  label?: string;
+  /** CSS class name for the button */
+  className?: string;
+  /** Inline styles */
+  style?: CSSProperties;
+  /** Custom render function. Receives signIn and status. */
+  children?: (props: {
+    signIn: () => void;
+    status: AuthStatus;
+  }) => ReactNode;
+  /** Disable the button */
+  disabled?: boolean;
+}
+
+/**
+ * "Sign in with Docyrus" button.
+ *
+ * In iframe mode: renders nothing (auth is handled by the host).
+ * When authenticated: renders nothing.
+ *
+ * Intentionally unstyled — use className, style, or the render-prop
+ * children pattern for full customization.
+ */
+export function SignInButton({
+  label = 'Sign in with Docyrus',
+  className,
+  style,
+  children,
+  disabled = false
+}: SignInButtonProps) {
+  const { signIn, status, mode } = useDocyrusAuth();
+
+  // In iframe mode, the host handles sign-in
+  if (mode === 'iframe') return null;
+
+  // Already authenticated
+  if (status === 'authenticated') return null;
+
+  // Custom render
+  if (children) {
+    return <>{children({ signIn, status })}</>;
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={signIn}
+      disabled={disabled || status === 'loading'}
+      className={className}
+      style={style}>
+      {status === 'loading' ? 'Loading...' : label}
+    </button>
+  );
+}

package/src/constants.ts

@@ -0,0 +1,24 @@
+export const DEFAULT_API_URL = 'https://alpha-api.docyrus.com';
+
+export const DEFAULT_OAUTH_CLIENT_ID = '90565525-8283-4881-82a9-8613eb82ae27';
+
+export const DEFAULT_OAUTH_SCOPES = [
+  'offline_access',
+  'Read.All',
+  'Users.Read',
+  'Users.Read.All',
+  'DS.Read.All'
+];
+
+export const DEFAULT_CALLBACK_PATH = '/auth/callback';
+
+export const DEFAULT_ALLOWED_HOST_PATTERN = /^https:\/\/[^/]+\.docyrus\.app$/;
+
+/** localStorage key to persist the pre-redirect location */
+export const REDIRECT_RETURN_KEY = 'docyrus_auth_return_url';
+
+/** Buffer in seconds before token expiration to trigger refresh */
+export const TOKEN_EXPIRY_BUFFER_SECONDS = 60;
+
+/** Timeout for iframe token refresh requests (ms) */
+export const IFRAME_TOKEN_REFRESH_TIMEOUT_MS = 10_000;

package/src/core/auth-detector.ts

@@ -0,0 +1,46 @@
+import { type AuthMode } from '../types';
+
+import { DEFAULT_ALLOWED_HOST_PATTERN } from '../constants';
+
+/**
+ * Detect whether the app is inside an iframe from a trusted *.docyrus.app host
+ * or running as a standalone page.
+ *
+ * If we are in an iframe but NOT from a trusted origin, we fall back
+ * to standalone mode (graceful degradation).
+ */
+export function detectAuthMode(
+  allowedOrigins?: string[],
+  allowedPattern?: RegExp
+): AuthMode {
+  if (typeof window === 'undefined') return 'standalone';
+
+  let isInIframe = false;
+
+  try {
+    isInIframe = window.self !== window.top;
+  } catch {
+    // Cross-origin iframe throws — so we ARE in an iframe
+    isInIframe = true;
+  }
+
+  if (!isInIframe) return 'standalone';
+
+  /*
+   * We're in an iframe. Verify the host origin is trusted via document.referrer.
+   * The actual security is enforced by validating event.origin on every postMessage.
+   */
+  const pattern = allowedPattern ?? DEFAULT_ALLOWED_HOST_PATTERN;
+
+  try {
+    const referrerOrigin = new URL(document.referrer).origin;
+
+    if (allowedOrigins?.includes(referrerOrigin)) return 'iframe';
+    if (pattern.test(referrerOrigin)) return 'iframe';
+  } catch {
+    // Invalid or empty referrer
+  }
+
+  // In iframe but not from a trusted host — treat as standalone
+  return 'standalone';
+}

package/src/core/auth-manager.ts

@@ -0,0 +1,312 @@
+import {
+  RestApiClient,
+  type OAuth2Tokens,
+  type TokenManager
+} from '@docyrus/api-client';
+
+import { type AuthMode, type AuthStatus, type DocyrusAuthConfig } from '../types';
+
+import { detectAuthMode } from './auth-detector';
+import { StandaloneOAuth2Auth } from './oauth2-auth';
+import { IframeAuth } from './iframe-auth';
+import { DEFAULT_API_URL, TOKEN_EXPIRY_BUFFER_SECONDS } from '../constants';
+
+export type AuthStateListener = (state: {
+  status: AuthStatus;
+  tokens: OAuth2Tokens | null;
+  error: Error | null;
+}) => void;
+
+/**
+ * Unified authentication manager.
+ * Orchestrates standalone OAuth2 and iframe postMessage modes,
+ * exposes a pre-configured RestApiClient, and manages token lifecycle.
+ */
+export class AuthManager {
+  private mode: AuthMode;
+  private status: AuthStatus = 'loading';
+  private tokens: OAuth2Tokens | null = null;
+  private error: Error | null = null;
+  private client: RestApiClient | null = null;
+  private standaloneAuth: StandaloneOAuth2Auth | null = null;
+  private iframeAuth: IframeAuth | null = null;
+  private tokenRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+  private listeners: Set<AuthStateListener> = new Set();
+  private config: DocyrusAuthConfig;
+  constructor(config: DocyrusAuthConfig = {}) {
+    this.config = config;
+    this.mode = config.forceMode
+      ?? detectAuthMode(config.allowedHostOrigins);
+  }
+  getMode(): AuthMode {
+    return this.mode;
+  }
+  getStatus(): AuthStatus {
+    return this.status;
+  }
+  getTokens(): OAuth2Tokens | null {
+    return this.tokens;
+  }
+  getClient(): RestApiClient | null {
+    return this.client;
+  }
+  getError(): Error | null {
+    return this.error;
+  }
+  subscribe(listener: AuthStateListener): () => void {
+    this.listeners.add(listener);
+
+    return () => this.listeners.delete(listener);
+  }
+  private notify(): void {
+    for (const listener of this.listeners) {
+      listener({
+        status: this.status,
+        tokens: this.tokens,
+        error: this.error
+      });
+    }
+  }
+  /** Initialize the auth manager. Must be called once on mount. */
+  async initialize(): Promise<void> {
+    try {
+      if (this.mode === 'iframe') {
+        this.initializeIframeMode();
+      } else {
+        await this.initializeStandaloneMode();
+      }
+    } catch (err) {
+      this.error = err instanceof Error ? err : new Error(String(err));
+      this.status = 'unauthenticated';
+      this.notify();
+    }
+  }
+  /**
+   * Standalone mode initialization.
+   * 1. Check if we're returning from an OAuth callback.
+   * 2. If not, check for existing tokens in localStorage.
+   * 3. If tokens are expired, try to refresh.
+   */
+  private async initializeStandaloneMode(): Promise<void> {
+    this.standaloneAuth = new StandaloneOAuth2Auth(this.config);
+
+    // Case 1: We're at the callback URL after OAuth redirect
+    if (this.standaloneAuth.isCallbackUrl()) {
+      const tokens = await this.standaloneAuth.handleCallback();
+
+      this.setAuthenticated(tokens);
+
+      // Navigate away from the callback URL
+      const returnUrl = this.standaloneAuth.getReturnUrl();
+
+      if (returnUrl) {
+        window.location.replace(returnUrl);
+      } else {
+        window.history.replaceState({}, '', '/');
+      }
+
+      return;
+    }
+
+    // Case 2: Check for existing tokens
+    const stored = await this.standaloneAuth.getStoredTokens();
+
+    if (stored) {
+      const isExpired = await this.standaloneAuth.isTokenExpired();
+
+      if (!isExpired) {
+        this.setAuthenticated(stored);
+
+        return;
+      }
+
+      // Token expired, try refresh
+      if (stored.refreshToken) {
+        try {
+          const newTokens = await this.standaloneAuth.refreshToken();
+
+          this.setAuthenticated(newTokens);
+
+          return;
+        } catch {
+          // Refresh failed, require re-login
+        }
+      }
+    }
+
+    // Case 3: No tokens or refresh failed
+    this.status = 'unauthenticated';
+    this.notify();
+  }
+  /**
+   * Iframe mode initialization.
+   * Listen for postMessage tokens from the host.
+   * Status remains 'loading' until the host sends the first signin message.
+   */
+  private initializeIframeMode(): void {
+    this.iframeAuth = new IframeAuth(this.config.allowedHostOrigins);
+
+    this.iframeAuth.start((tokens: OAuth2Tokens) => {
+      this.setAuthenticated(tokens);
+    });
+  }
+  /** Initiate sign-in. Only meaningful in standalone mode. */
+  async signIn(): Promise<void> {
+    if (this.mode !== 'standalone' || !this.standaloneAuth) return;
+
+    await this.standaloneAuth.initiateLogin();
+  }
+  /**
+   * Sign out.
+   * Standalone: revoke token, clear localStorage, reset state.
+   * Iframe: clear local state (host manages the actual session).
+   */
+  async signOut(): Promise<void> {
+    this.clearTokenRefreshTimer();
+
+    if (this.mode === 'standalone' && this.standaloneAuth) {
+      await this.standaloneAuth.logout();
+    }
+
+    if (this.mode === 'iframe' && this.iframeAuth) {
+      this.iframeAuth.stop();
+    }
+
+    this.tokens = null;
+    this.client = null;
+    this.status = 'unauthenticated';
+    this.error = null;
+    this.notify();
+  }
+  /**
+   * Called when valid tokens are received (either mode).
+   * Creates/updates the RestApiClient and schedules token refresh.
+   */
+  private setAuthenticated(tokens: OAuth2Tokens): void {
+    this.tokens = tokens;
+    this.error = null;
+    this.status = 'authenticated';
+
+    this.createClient();
+    this.scheduleTokenRefresh(tokens);
+    this.notify();
+  }
+  /**
+   * Create a RestApiClient with a custom TokenManager that proactively
+   * refreshes the token in getToken(). This is necessary because
+   * BaseApiClient.getAccessToken() only calls tokenManager.getToken()
+   * and does NOT auto-call refreshToken() when the token is expired.
+   */
+  private createClient(): void {
+    const apiUrl = this.config.apiUrl ?? DEFAULT_API_URL;
+
+    const tokenManager: TokenManager = {
+      getToken: () => this.getValidToken(),
+      setToken: (token: string) => {
+        if (this.tokens) {
+          this.tokens = { ...this.tokens, accessToken: token };
+        }
+      },
+      clearToken: () => {
+        this.tokens = null;
+      },
+      refreshToken: () => this.handleTokenRefresh()
+    };
+
+    this.client = new RestApiClient({
+      baseURL: apiUrl,
+      tokenManager
+    });
+  }
+  /**
+   * Get a valid access token, proactively refreshing if expired.
+   * Called by the RestApiClient on every request via tokenManager.getToken().
+   */
+  private async getValidToken(): Promise<string | null> {
+    if (!this.tokens) return null;
+
+    // Check if token is expired (with buffer)
+    if (this.tokens.expiresAt) {
+      const nowSec = Math.floor(Date.now() / 1000);
+
+      if (nowSec >= this.tokens.expiresAt - TOKEN_EXPIRY_BUFFER_SECONDS) {
+        try {
+          const freshToken = await this.handleTokenRefresh();
+
+          return freshToken;
+        } catch {
+          return null;
+        }
+      }
+    }
+
+    return this.tokens.accessToken;
+  }
+  /**
+   * Handle token refresh depending on mode.
+   * Standalone: use OAuth2Client.getValidAccessToken() which auto-refreshes.
+   * Iframe: send postMessage to host requesting new tokens.
+   */
+  private async handleTokenRefresh(): Promise<string> {
+    if (this.mode === 'standalone' && this.standaloneAuth) {
+      const newTokens = await this.standaloneAuth.refreshToken();
+
+      this.tokens = newTokens;
+      this.scheduleTokenRefresh(newTokens);
+      this.notify();
+
+      return newTokens.accessToken;
+    }
+
+    if (this.mode === 'iframe' && this.iframeAuth) {
+      const newTokens = await this.iframeAuth.requestTokenRefresh();
+
+      return newTokens.accessToken;
+    }
+
+    throw new Error('Cannot refresh token: auth not initialized');
+  }
+  /** Schedule proactive token refresh before expiry. */
+  private scheduleTokenRefresh(tokens: OAuth2Tokens): void {
+    this.clearTokenRefreshTimer();
+
+    if (!tokens.expiresAt) return;
+
+    const expiresAtMs = tokens.expiresAt * 1000;
+    const bufferMs = TOKEN_EXPIRY_BUFFER_SECONDS * 1000;
+    const refreshInMs = expiresAtMs - bufferMs - Date.now();
+
+    if (refreshInMs <= 0) {
+      // Already needs refresh
+      this.handleTokenRefresh().catch((err) => {
+        this.error = err instanceof Error ? err : new Error(String(err));
+        this.status = 'unauthenticated';
+        this.notify();
+      });
+
+      return;
+    }
+
+    this.tokenRefreshTimer = setTimeout(() => {
+      this.handleTokenRefresh().catch((err) => {
+        this.error = err instanceof Error ? err : new Error(String(err));
+        this.status = 'unauthenticated';
+        this.notify();
+      });
+    }, refreshInMs);
+  }
+  private clearTokenRefreshTimer(): void {
+    if (this.tokenRefreshTimer) {
+      clearTimeout(this.tokenRefreshTimer);
+      this.tokenRefreshTimer = null;
+    }
+  }
+  /** Cleanup: remove listeners, timers, stop iframe auth. */
+  destroy(): void {
+    this.clearTokenRefreshTimer();
+
+    if (this.iframeAuth) this.iframeAuth.stop();
+
+    this.listeners.clear();
+  }
+}