@docyrus/app-auth-ui 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,17 @@
+
+> @docyrus/app-auth-ui@0.0.1 build /Volumes/Developer/tools/docyrus-devkit/packages/app-auth-ui
+> tsup
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /Volumes/Developer/tools/docyrus-devkit/packages/app-auth-ui/tsup.config.ts
+CLI Target: es2024
+CLI Cleaning output folder
+ESM Build start
+ESM dist/index.js     16.94 KB
+ESM dist/index.js.map 38.56 KB
+ESM ⚡️ Build success in 61ms
+DTS Build start
+DTS ⚡️ Build success in 470ms
+DTS dist/index.d.ts 10.56 KB

package/.turbo/turbo-typecheck.log

@@ -0,0 +1,5 @@
+
+> @docyrus/app-auth-ui@0.0.1 typecheck /Volumes/Developer/tools/docyrus-devkit/packages/app-auth-ui
+> eslint src && tsc --noEmit
+
+Pages directory cannot be found at /Volumes/Developer/tools/docyrus-devkit/packages/app-auth-ui/pages or /Volumes/Developer/tools/docyrus-devkit/packages/app-auth-ui/src/pages. If using a custom path, please configure with the `no-html-link-for-pages` rule in your eslint config file.

package/README.md

@@ -0,0 +1,200 @@
+# @docyrus/app-auth-ui
+
+React authentication provider for Docyrus apps. Provides "Sign in with Docyrus" experience with automatic environment detection — standalone apps use OAuth2 Authorization Code + PKCE via page redirect, while iframe-embedded apps receive tokens via `window.postMessage` from the host.
+
+## Features
+
+- **Auto Environment Detection**: Detects standalone vs iframe mode automatically
+- **OAuth2 PKCE**: Full Authorization Code flow with PKCE (S256) for standalone apps
+- **Iframe Auth**: Receives tokens via `postMessage` from `*.docyrus.app` hosts
+- **Token Auto-Refresh**: Proactive token refresh before expiry in both modes
+- **React Hooks**: `useDocyrusAuth()` and `useDocyrusClient()` for easy integration
+- **Ready-to-Use API Client**: Exposes a configured `RestApiClient` from `@docyrus/api-client`
+- **SignInButton**: Unstyled, customizable sign-in button component
+- **TypeScript**: Full type definitions included
+
+## Installation
+
+```bash
+npm install @docyrus/app-auth-ui
+```
+
+```bash
+pnpm add @docyrus/app-auth-ui
+```
+
+### Peer Dependencies
+
+- `react` >= 18.0.0
+- `@docyrus/api-client` >= 0.0.4
+
+## Quick Start
+
+```tsx
+import { DocyrusAuthProvider, useDocyrusAuth, useDocyrusClient, SignInButton } from '@docyrus/app-auth-ui';
+
+function App() {
+  return (
+    <DocyrusAuthProvider>
+      <Dashboard />
+    </DocyrusAuthProvider>
+  );
+}
+
+function Dashboard() {
+  const { status, signOut } = useDocyrusAuth();
+  const client = useDocyrusClient();
+
+  if (status === 'loading') return <div>Loading...</div>;
+  if (status === 'unauthenticated') return <SignInButton />;
+
+  return (
+    <div>
+      <p>Authenticated!</p>
+      <button onClick={() => client!.get('/v1/users/me').then(console.log)}>
+        Fetch user
+      </button>
+      <button onClick={signOut}>Sign out</button>
+    </div>
+  );
+}
+```
+
+## Configuration
+
+Pass props to `DocyrusAuthProvider` to override defaults:
+
+```tsx
+<DocyrusAuthProvider
+  apiUrl="https://alpha-api.docyrus.com"
+  clientId="your-oauth2-client-id"
+  redirectUri="http://localhost:3000/auth/callback"
+  scopes={['offline_access', 'Read.All', 'Users.Read']}
+  callbackPath="/auth/callback"
+  forceMode="standalone"
+>
+  <App />
+</DocyrusAuthProvider>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | `https://alpha-api.docyrus.com` | Docyrus API base URL |
+| `clientId` | `string` | Built-in default | OAuth2 client ID |
+| `redirectUri` | `string` | `window.location.origin + callbackPath` | OAuth2 redirect URI |
+| `scopes` | `string[]` | `['offline_access', 'Read.All', ...]` | OAuth2 scopes |
+| `callbackPath` | `string` | `/auth/callback` | Path to detect OAuth callback |
+| `forceMode` | `'standalone' \| 'iframe'` | Auto-detected | Force a specific auth mode |
+| `storageKeyPrefix` | `string` | `docyrus_oauth2_` | localStorage key prefix |
+| `allowedHostOrigins` | `string[]` | `undefined` | Extra trusted iframe origins |
+
+## Hooks
+
+### useDocyrusAuth()
+
+Returns the full authentication context:
+
+```tsx
+const {
+  status,  // 'loading' | 'authenticated' | 'unauthenticated'
+  mode,    // 'standalone' | 'iframe'
+  client,  // RestApiClient | null
+  tokens,  // { accessToken, refreshToken, ... } | null
+  signIn,  // () => void (redirects to Docyrus login)
+  signOut, // () => void
+  error    // Error | null
+} = useDocyrusAuth();
+```
+
+### useDocyrusClient()
+
+Shorthand hook that returns just the API client:
+
+```tsx
+const client = useDocyrusClient(); // RestApiClient | null
+
+if (client) {
+  const response = await client.get('/v1/users/me');
+}
+```
+
+## Components
+
+### SignInButton
+
+Unstyled button that triggers sign-in. Automatically hidden when authenticated or in iframe mode.
+
+```tsx
+// Basic
+<SignInButton />
+
+// With custom styling
+<SignInButton className="btn btn-primary" label="Log in with Docyrus" />
+
+// Render prop for full customization
+<SignInButton>
+  {({ signIn, isLoading }) => (
+    <button onClick={signIn} disabled={isLoading}>
+      {isLoading ? 'Redirecting...' : 'Sign in'}
+    </button>
+  )}
+</SignInButton>
+```
+
+## Auth Modes
+
+### Standalone Mode (OAuth2 PKCE)
+
+Used when the app runs directly in the browser (not in an iframe). The flow:
+
+1. User clicks sign-in
+2. Page redirects to Docyrus authorization endpoint
+3. After login, redirects back with authorization code
+4. Provider automatically exchanges code for tokens
+5. Tokens stored in localStorage, auto-refreshed before expiry
+
+### Iframe Mode (postMessage)
+
+Used when the app is embedded in an iframe on `*.docyrus.app`. The flow:
+
+1. Provider detects iframe environment and validates host origin
+2. Host sends `{ type: 'signin', accessToken, refreshToken }` via `postMessage`
+3. Provider creates API client with received tokens
+4. When tokens expire, provider sends `{ type: 'token-refresh-request' }` to host
+5. Host responds with fresh tokens
+
+## Advanced Usage
+
+Core classes are exported for advanced use cases:
+
+```tsx
+import {
+  AuthManager,
+  StandaloneOAuth2Auth,
+  IframeAuth,
+  detectAuthMode
+} from '@docyrus/app-auth-ui';
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Development mode with watch
+pnpm dev
+
+# Build the package
+pnpm build
+
+# Run linting
+pnpm lint
+
+# Type checking
+pnpm typecheck
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,286 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+import { RestApiClient, OAuth2Tokens } from '@docyrus/api-client';
+
+/** Authentication mode detected at runtime */
+type AuthMode = 'standalone' | 'iframe';
+/** Authentication state exposed to consumers */
+type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
+/** Configuration for the DocyrusAuthProvider */
+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 */
+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 */
+interface HostSignInMessage {
+    type: 'signin';
+    accessToken: string;
+    refreshToken: string;
+}
+/** PostMessage payload: app requests fresh tokens from the host */
+interface TokenRefreshRequestMessage {
+    type: 'token-refresh-request';
+}
+
+declare const DocyrusAuthContext: react.Context<DocyrusAuthContextValue | null>;
+interface DocyrusAuthProviderProps extends DocyrusAuthConfig {
+    children: ReactNode;
+}
+declare function DocyrusAuthProvider({ children, ...config }: DocyrusAuthProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook to access Docyrus auth state.
+ * Must be used within a <DocyrusAuthProvider>.
+ *
+ * Returns: { status, mode, tokens, signIn, signOut, client, error }
+ */
+declare function useDocyrusAuth(): DocyrusAuthContextValue;
+
+/**
+ * Hook to get the pre-configured RestApiClient.
+ * Returns null when not authenticated.
+ *
+ * Throws if used outside DocyrusAuthProvider.
+ */
+declare function useDocyrusClient(): RestApiClient | null;
+
+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.
+ */
+declare function SignInButton({ label, className, style, children, disabled }: SignInButtonProps): react_jsx_runtime.JSX.Element | null;
+
+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.
+ */
+declare class AuthManager {
+    private mode;
+    private status;
+    private tokens;
+    private error;
+    private client;
+    private standaloneAuth;
+    private iframeAuth;
+    private tokenRefreshTimer;
+    private listeners;
+    private config;
+    constructor(config?: DocyrusAuthConfig);
+    getMode(): AuthMode;
+    getStatus(): AuthStatus;
+    getTokens(): OAuth2Tokens | null;
+    getClient(): RestApiClient | null;
+    getError(): Error | null;
+    subscribe(listener: AuthStateListener): () => void;
+    private notify;
+    /** Initialize the auth manager. Must be called once on mount. */
+    initialize(): Promise<void>;
+    /**
+     * 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 initializeStandaloneMode;
+    /**
+     * Iframe mode initialization.
+     * Listen for postMessage tokens from the host.
+     * Status remains 'loading' until the host sends the first signin message.
+     */
+    private initializeIframeMode;
+    /** Initiate sign-in. Only meaningful in standalone mode. */
+    signIn(): Promise<void>;
+    /**
+     * Sign out.
+     * Standalone: revoke token, clear localStorage, reset state.
+     * Iframe: clear local state (host manages the actual session).
+     */
+    signOut(): Promise<void>;
+    /**
+     * Called when valid tokens are received (either mode).
+     * Creates/updates the RestApiClient and schedules token refresh.
+     */
+    private setAuthenticated;
+    /**
+     * 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;
+    /**
+     * Get a valid access token, proactively refreshing if expired.
+     * Called by the RestApiClient on every request via tokenManager.getToken().
+     */
+    private getValidToken;
+    /**
+     * Handle token refresh depending on mode.
+     * Standalone: use OAuth2Client.getValidAccessToken() which auto-refreshes.
+     * Iframe: send postMessage to host requesting new tokens.
+     */
+    private handleTokenRefresh;
+    /** Schedule proactive token refresh before expiry. */
+    private scheduleTokenRefresh;
+    private clearTokenRefreshTimer;
+    /** Cleanup: remove listeners, timers, stop iframe auth. */
+    destroy(): void;
+}
+
+/**
+ * Standalone OAuth2 authorization code flow with PKCE via page redirect.
+ * Wraps api-client's OAuth2Client and BrowserOAuth2TokenStorage.
+ */
+declare class StandaloneOAuth2Auth {
+    private oauth2Client;
+    private storage;
+    private callbackPath;
+    constructor(config?: DocyrusAuthConfig);
+    /**
+     * Check if the current page URL is the OAuth2 callback.
+     * Called on app initialization to detect returning from the auth server.
+     */
+    isCallbackUrl(): boolean;
+    /**
+     * 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.
+     */
+    initiateLogin(): Promise<void>;
+    /**
+     * Handle the OAuth2 callback URL.
+     * Reads PKCE state from localStorage, validates the state param,
+     * exchanges the authorization code for tokens, and stores them.
+     */
+    handleCallback(): Promise<OAuth2Tokens>;
+    /**
+     * Get the URL the user was on before the OAuth redirect.
+     * Clears the stored value after retrieval.
+     */
+    getReturnUrl(): string | null;
+    /** Get currently stored tokens (e.g., on page reload). */
+    getStoredTokens(): Promise<OAuth2Tokens | null>;
+    /** Check if the stored token is expired (with 60s buffer). */
+    isTokenExpired(): Promise<boolean>;
+    /** Refresh the access token using the stored refresh token. */
+    refreshToken(): Promise<OAuth2Tokens>;
+    /** Get a valid access token, refreshing if needed. */
+    getValidAccessToken(): Promise<string>;
+    /** Logout: revoke token and clear storage. */
+    logout(): Promise<void>;
+}
+
+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.
+ */
+declare class IframeAuth {
+    private allowedOrigins;
+    private allowedPattern;
+    private onTokensReceived;
+    private refreshPromise;
+    private messageHandler;
+    constructor(allowedOrigins?: string[], allowedPattern?: RegExp);
+    /**
+     * Start listening for postMessage events from the host.
+     * The callback is invoked every time valid tokens are received.
+     */
+    start(onTokensReceived: IframeAuthCallback): void;
+    /** Stop listening for postMessage events. */
+    stop(): void;
+    /**
+     * 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>;
+    private isOriginAllowed;
+    private handleMessage;
+    private rejectPendingRefresh;
+}
+
+/**
+ * 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).
+ */
+declare function detectAuthMode(allowedOrigins?: string[], allowedPattern?: RegExp): AuthMode;
+
+declare const DEFAULT_API_URL = "https://alpha-api.docyrus.com";
+declare const DEFAULT_OAUTH_CLIENT_ID = "90565525-8283-4881-82a9-8613eb82ae27";
+declare const DEFAULT_OAUTH_SCOPES: string[];
+declare const DEFAULT_CALLBACK_PATH = "/auth/callback";
+
+export { AuthManager, type AuthMode, type AuthStatus, DEFAULT_API_URL, DEFAULT_CALLBACK_PATH, DEFAULT_OAUTH_CLIENT_ID, DEFAULT_OAUTH_SCOPES, type DocyrusAuthConfig, DocyrusAuthContext, type DocyrusAuthContextValue, DocyrusAuthProvider, type DocyrusAuthProviderProps, type HostSignInMessage, IframeAuth, SignInButton, type SignInButtonProps, StandaloneOAuth2Auth, type TokenRefreshRequestMessage, detectAuthMode, useDocyrusAuth, useDocyrusClient };