@docyrus/app-auth-ui 0.0.1

package/src/core/iframe-auth.ts

@@ -0,0 +1,135 @@
+import { type OAuth2Tokens } from '@docyrus/api-client';
+
+import { type HostSignInMessage, type HostToAppMessage } from '../types';
+
+import {
+  DEFAULT_ALLOWED_HOST_PATTERN,
+  IFRAME_TOKEN_REFRESH_TIMEOUT_MS
+} from '../constants';
+
+type IframeAuthCallback = (tokens: OAuth2Tokens) => void;
+
+/**
+ * Iframe authentication via postMessage.
+ *
+ * Protocol:
+ * - Host → App: { type: "signin", accessToken, refreshToken }
+ * - App → Host: { type: "token-refresh-request" }
+ *
+ * Every incoming message's event.origin is validated against
+ * the allowed host pattern before processing.
+ */
+export class IframeAuth {
+  private allowedOrigins: string[];
+  private allowedPattern: RegExp;
+  private onTokensReceived: IframeAuthCallback | null = null;
+  private refreshPromise: {
+    resolve: (tokens: OAuth2Tokens) => void;
+    reject: (error: Error) => void;
+    timeoutId: ReturnType<typeof setTimeout>;
+  } | null = null;
+  private messageHandler: ((ev: MessageEvent) => void) | null = null;
+  constructor(
+    allowedOrigins?: string[],
+    allowedPattern?: RegExp
+  ) {
+    this.allowedOrigins = allowedOrigins ?? [];
+    this.allowedPattern = allowedPattern ?? DEFAULT_ALLOWED_HOST_PATTERN;
+  }
+  /**
+   * Start listening for postMessage events from the host.
+   * The callback is invoked every time valid tokens are received.
+   */
+  start(onTokensReceived: IframeAuthCallback): void {
+    this.onTokensReceived = onTokensReceived;
+    this.messageHandler = this.handleMessage.bind(this);
+    window.addEventListener('message', this.messageHandler);
+  }
+  /** Stop listening for postMessage events. */
+  stop(): void {
+    if (this.messageHandler) {
+      window.removeEventListener('message', this.messageHandler);
+      this.messageHandler = null;
+    }
+    this.rejectPendingRefresh('IframeAuth stopped');
+  }
+  /**
+   * Request fresh tokens from the host.
+   * Posts a "token-refresh-request" to the host, then waits for
+   * a "signin" response.
+   *
+   * Only one refresh request can be in-flight at a time.
+   * Additional callers share the same promise.
+   */
+  requestTokenRefresh(): Promise<OAuth2Tokens> {
+    if (this.refreshPromise) {
+      return new Promise<OAuth2Tokens>((resolve, reject) => {
+        const existing = this.refreshPromise!;
+        const originalResolve = existing.resolve;
+        const originalReject = existing.reject;
+
+        existing.resolve = (tokens) => {
+          originalResolve(tokens);
+          resolve(tokens);
+        };
+        existing.reject = (error) => {
+          originalReject(error);
+          reject(error);
+        };
+      });
+    }
+
+    return new Promise<OAuth2Tokens>((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.refreshPromise = null;
+        reject(new Error('Token refresh request timed out'));
+      }, IFRAME_TOKEN_REFRESH_TIMEOUT_MS);
+
+      this.refreshPromise = { resolve, reject, timeoutId };
+
+      window.parent.postMessage({ type: 'token-refresh-request' }, '*');
+    });
+  }
+  private isOriginAllowed(origin: string): boolean {
+    if (this.allowedOrigins.includes(origin)) return true;
+
+    return this.allowedPattern.test(origin);
+  }
+  private handleMessage(ev: MessageEvent): void {
+    if (!this.isOriginAllowed(ev.origin)) return;
+
+    const data = ev.data as HostToAppMessage;
+
+    if (!data || typeof data !== 'object' || data.type !== 'signin') return;
+
+    const signinData = data as HostSignInMessage;
+
+    if (!signinData.accessToken) return;
+
+    const tokens: OAuth2Tokens = {
+      accessToken: signinData.accessToken,
+      refreshToken: signinData.refreshToken,
+      /*
+       * We don't know the exact expiry from the host, so estimate 1 hour.
+       * The host will send new tokens before expiry via the refresh mechanism.
+       */
+      expiresAt: Math.floor(Date.now() / 1000) + 3600,
+      scope: ''
+    };
+
+    this.onTokensReceived?.(tokens);
+
+    if (this.refreshPromise) {
+      clearTimeout(this.refreshPromise.timeoutId);
+      this.refreshPromise.resolve(tokens);
+      this.refreshPromise = null;
+    }
+  }
+  private rejectPendingRefresh(reason: string): void {
+    if (this.refreshPromise) {
+      clearTimeout(this.refreshPromise.timeoutId);
+      this.refreshPromise.reject(new Error(reason));
+      this.refreshPromise = null;
+    }
+  }
+}

package/src/core/oauth2-auth.ts

@@ -0,0 +1,111 @@
+import {
+  OAuth2Client,
+  BrowserOAuth2TokenStorage,
+  type OAuth2Tokens
+} from '@docyrus/api-client';
+
+import { type DocyrusAuthConfig } from '../types';
+
+import {
+  DEFAULT_API_URL,
+  DEFAULT_OAUTH_CLIENT_ID,
+  DEFAULT_OAUTH_SCOPES,
+  DEFAULT_CALLBACK_PATH,
+  REDIRECT_RETURN_KEY
+} from '../constants';
+
+/**
+ * Standalone OAuth2 authorization code flow with PKCE via page redirect.
+ * Wraps api-client's OAuth2Client and BrowserOAuth2TokenStorage.
+ */
+export class StandaloneOAuth2Auth {
+  private oauth2Client: OAuth2Client;
+  private storage: BrowserOAuth2TokenStorage;
+  private callbackPath: string;
+  constructor(config: DocyrusAuthConfig = {}) {
+    const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
+    const clientId = config.clientId ?? DEFAULT_OAUTH_CLIENT_ID;
+    const scopes = config.scopes ?? DEFAULT_OAUTH_SCOPES;
+
+    this.callbackPath = config.callbackPath ?? DEFAULT_CALLBACK_PATH;
+    const redirectUri = config.redirectUri
+      ?? `${window.location.origin}${this.callbackPath}`;
+
+    this.storage = new BrowserOAuth2TokenStorage(
+      window.localStorage,
+      config.storageKeyPrefix ?? 'docyrus_oauth2'
+    );
+
+    this.oauth2Client = new OAuth2Client({
+      baseURL: apiUrl,
+      clientId,
+      redirectUri,
+      defaultScopes: scopes,
+      usePKCE: true,
+      tokenStorage: this.storage
+    });
+  }
+  /**
+   * Check if the current page URL is the OAuth2 callback.
+   * Called on app initialization to detect returning from the auth server.
+   */
+  isCallbackUrl(): boolean {
+    return window.location.pathname === this.callbackPath
+      && (window.location.search.includes('code=')
+        || window.location.search.includes('error='));
+  }
+  /**
+   * Initiate the OAuth2 authorization code flow.
+   * Stores the current URL for post-auth redirect, then navigates
+   * the page to the authorization endpoint.
+   *
+   * PKCE state (codeVerifier, state) is stored in localStorage
+   * by the OAuth2Client and survives the page redirect.
+   */
+  async initiateLogin(): Promise<void> {
+    window.localStorage.setItem(REDIRECT_RETURN_KEY, window.location.href);
+
+    const { url } = await this.oauth2Client.getAuthorizationUrl();
+
+    window.location.href = url;
+  }
+  /**
+   * Handle the OAuth2 callback URL.
+   * Reads PKCE state from localStorage, validates the state param,
+   * exchanges the authorization code for tokens, and stores them.
+   */
+  async handleCallback(): Promise<OAuth2Tokens> {
+    return this.oauth2Client.handleCallback(window.location.href);
+  }
+  /**
+   * Get the URL the user was on before the OAuth redirect.
+   * Clears the stored value after retrieval.
+   */
+  getReturnUrl(): string | null {
+    const url = window.localStorage.getItem(REDIRECT_RETURN_KEY);
+
+    window.localStorage.removeItem(REDIRECT_RETURN_KEY);
+
+    return url;
+  }
+  /** Get currently stored tokens (e.g., on page reload). */
+  async getStoredTokens(): Promise<OAuth2Tokens | null> {
+    return this.oauth2Client.getTokens();
+  }
+  /** Check if the stored token is expired (with 60s buffer). */
+  async isTokenExpired(): Promise<boolean> {
+    return this.oauth2Client.isTokenExpired();
+  }
+  /** Refresh the access token using the stored refresh token. */
+  async refreshToken(): Promise<OAuth2Tokens> {
+    return this.oauth2Client.refreshAccessToken();
+  }
+  /** Get a valid access token, refreshing if needed. */
+  async getValidAccessToken(): Promise<string> {
+    return this.oauth2Client.getValidAccessToken();
+  }
+  /** Logout: revoke token and clear storage. */
+  async logout(): Promise<void> {
+    return this.oauth2Client.logout();
+  }
+}

package/src/hooks/use-docyrus-auth.ts

@@ -0,0 +1,24 @@
+import { useContext } from 'react';
+
+import { type DocyrusAuthContextValue } from '../types';
+
+import { DocyrusAuthContext } from '../components/docyrus-auth-provider';
+
+/**
+ * Hook to access Docyrus auth state.
+ * Must be used within a <DocyrusAuthProvider>.
+ *
+ * Returns: { status, mode, tokens, signIn, signOut, client, error }
+ */
+export function useDocyrusAuth(): DocyrusAuthContextValue {
+  const context = useContext(DocyrusAuthContext);
+
+  if (!context) {
+    throw new Error(
+      'useDocyrusAuth must be used within a <DocyrusAuthProvider>. '
+      + 'Wrap your app with <DocyrusAuthProvider> to provide auth context.'
+    );
+  }
+
+  return context;
+}

package/src/hooks/use-docyrus-client.ts

@@ -0,0 +1,15 @@
+import { type RestApiClient } from '@docyrus/api-client';
+
+import { useDocyrusAuth } from './use-docyrus-auth';
+
+/**
+ * Hook to get the pre-configured RestApiClient.
+ * Returns null when not authenticated.
+ *
+ * Throws if used outside DocyrusAuthProvider.
+ */
+export function useDocyrusClient(): RestApiClient | null {
+  const { client } = useDocyrusAuth();
+
+  return client;
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// Provider
+export { DocyrusAuthProvider, DocyrusAuthContext } from './components/docyrus-auth-provider';
+export type { DocyrusAuthProviderProps } from './components/docyrus-auth-provider';
+
+// Hooks
+export { useDocyrusAuth } from './hooks/use-docyrus-auth';
+export { useDocyrusClient } from './hooks/use-docyrus-client';
+
+// Component
+export { SignInButton } from './components/sign-in-button';
+export type { SignInButtonProps } from './components/sign-in-button';
+
+// Core classes (for advanced usage)
+export { AuthManager } from './core/auth-manager';
+export { StandaloneOAuth2Auth } from './core/oauth2-auth';
+export { IframeAuth } from './core/iframe-auth';
+export { detectAuthMode } from './core/auth-detector';
+
+// Types
+export type {
+  AuthMode,
+  AuthStatus,
+  DocyrusAuthContextValue,
+  DocyrusAuthConfig,
+  HostSignInMessage,
+  TokenRefreshRequestMessage
+} from './types';
+
+// Constants
+export {
+  DEFAULT_API_URL,
+  DEFAULT_OAUTH_CLIENT_ID,
+  DEFAULT_OAUTH_SCOPES,
+  DEFAULT_CALLBACK_PATH
+} from './constants';

package/src/types.ts

@@ -0,0 +1,60 @@
+import { type OAuth2Tokens, type RestApiClient } from '@docyrus/api-client';
+
+/** Authentication mode detected at runtime */
+export type AuthMode = 'standalone' | 'iframe';
+
+/** Authentication state exposed to consumers */
+export type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
+
+/** Configuration for the DocyrusAuthProvider */
+export interface DocyrusAuthConfig {
+  /** OAuth2 client ID. Defaults to the Docyrus public client ID */
+  clientId?: string;
+  /** API base URL. Defaults to https://alpha-api.docyrus.com */
+  apiUrl?: string;
+  /** OAuth2 scopes. Defaults to offline_access Read.All Users.Read Users.Read.All DS.Read.All */
+  scopes?: string[];
+  /** The redirect URI for OAuth2 callback. Defaults to `${window.location.origin}/auth/callback` */
+  redirectUri?: string;
+  /** The path where the OAuth2 callback is handled. Defaults to '/auth/callback' */
+  callbackPath?: string;
+  /** Allowed host origins for iframe mode. Used alongside the default *.docyrus.app pattern */
+  allowedHostOrigins?: string[];
+  /** localStorage key prefix for token storage. Defaults to 'docyrus_oauth2' */
+  storageKeyPrefix?: string;
+  /** Override auto-detection: force a specific auth mode */
+  forceMode?: AuthMode;
+}
+
+/** The shape of the React context value */
+export interface DocyrusAuthContextValue {
+  /** Current auth state */
+  status: AuthStatus;
+  /** The detected authentication mode */
+  mode: AuthMode | null;
+  /** Pre-configured RestApiClient with valid tokens */
+  client: RestApiClient | null;
+  /** Current tokens (null when unauthenticated) */
+  tokens: OAuth2Tokens | null;
+  /** Initiate sign-in (only relevant in standalone mode) */
+  signIn: () => void;
+  /** Sign out and clear tokens */
+  signOut: () => Promise<void>;
+  /** Any error that occurred during auth */
+  error: Error | null;
+}
+
+/** PostMessage payload: host sends tokens to the embedded app */
+export interface HostSignInMessage {
+  type: 'signin';
+  accessToken: string;
+  refreshToken: string;
+}
+
+/** PostMessage payload: app requests fresh tokens from the host */
+export interface TokenRefreshRequestMessage {
+  type: 'token-refresh-request';
+}
+
+export type HostToAppMessage = HostSignInMessage;
+export type AppToHostMessage = TokenRefreshRequestMessage;

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": [ "ES2024", "DOM", "DOM.Iterable" ],
+    "jsx": "react-jsx",
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": [ "src" ]
+}

package/tsup.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  treeshake: true,
+  minify: false,
+  esbuildOptions(options) {
+    options.jsx = 'automatic';
+  }
+});