@proyecta-ai/auth

OIDC authentication provider for Proyecta apps. Wraps react-oidc-context with Proyecta-specific configuration for the Proyecta auth server.

Installation

npm install @proyecta-ai/auth

Peer dependencies:

npm install react convex

Entry Points

The package has two entry points:

• @proyecta-ai/auth/react -- Core auth provider, hooks, and re-exports from react-oidc-context
• @proyecta-ai/auth/convex-react -- Convex integration (authenticated ConvexReactClient via Proyecta OIDC)

Usage

Basic Setup (@proyecta-ai/auth/react)

Wrap your app with ProyectaAuthProvider, passing your OIDC authority URL and client ID:

import { ProyectaAuthProvider } from '@proyecta-ai/auth/react';

function App() {
    return (
        <ProyectaAuthProvider
            authority={import.meta.env.VITE_PROYECTA_OIDC_AUTHORITY}
            client_id={import.meta.env.VITE_PROYECTA_OIDC_CLIENT_ID}
        >
            <MyApp />
        </ProyectaAuthProvider>
    );
}

You can pass additional OIDC settings via userManagerSettings:

<ProyectaAuthProvider
    authority={authority}
    client_id={clientId}
    userManagerSettings={{
        popup_redirect_uri: `${window.location.origin}/popup-callback.html`,
        scope: 'openid profile email',
        disablePKCE: !window.isSecureContext,
    }}
>
    {children}
</ProyectaAuthProvider>

Accessing the User

Use useUser for a simplified user object, or useAuth (re-exported from react-oidc-context) for full OIDC context:

import { useUser } from '@proyecta-ai/auth/react';

function Profile() {
    const { id, name, email, avatar, isAuthenticated, isLoading, error } = useUser();

    if (isLoading) return <div>Loading...</div>;
    if (!isAuthenticated) return <div>Not signed in</div>;

    return <div>Hello, {name}</div>;
}

import { useAuth } from '@proyecta-ai/auth/react';

function LoginButton() {
    const { isAuthenticated, signinPopup, removeUser } = useAuth();

    return isAuthenticated ? (
        <button onClick={() => removeUser()}>Sign out</button>
    ) : (
        <button onClick={() => signinPopup()}>Sign in</button>
    );
}

Handling Auth Callbacks (useAuthCallback)

For redirect-based auth flows, use useAuthCallback on your /auth/callback route:

import { useAuthCallback } from '@proyecta-ai/auth/react';

function AuthCallback() {
    const { status, error, retry } = useAuthCallback({
        isBackendAuthenticated: true, // or e.g. useConvexAuth().isAuthenticated
        onSync: () => updateUserInBackend(),
        onSuccess: () => navigate('/', { replace: true }),
        onNoAuthParams: () => navigate('/', { replace: true }),
    });

    if (status === 'error') {
        return <button onClick={retry}>Retry: {error}</button>;
    }

    return <div>Authenticating...</div>;
}

Convex Integration (@proyecta-ai/auth/convex-react)

ConvexProviderWithProyectaAuth wraps Convex's ConvexProviderWithAuth and passes the OIDC id_token to Convex. It must be placed inside ProyectaAuthProvider:

import { ProyectaAuthProvider } from '@proyecta-ai/auth/react';
import { ConvexProviderWithProyectaAuth } from '@proyecta-ai/auth/convex-react';
import { ConvexReactClient } from 'convex/react';

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

function App() {
    return (
        <ProyectaAuthProvider
            authority={import.meta.env.VITE_PROYECTA_OIDC_AUTHORITY}
            client_id={import.meta.env.VITE_PROYECTA_OIDC_CLIENT_ID}
        >
            <ConvexProviderWithProyectaAuth client={convex}>
                <MyApp />
            </ConvexProviderWithProyectaAuth>
        </ProyectaAuthProvider>
    );
}

Exports

@proyecta-ai/auth/react

| Export | Type | Description | | ---------------------- | --------- | ----------------------------------------------------------------- | | ProyectaAuthProvider | Component | OIDC auth provider configured for Proyecta | | useUser | Hook | Simplified user object (id, name, email, avatar, isAuthenticated) | | useAuthCallback | Hook | Manages OAuth redirect callback lifecycle | | useAuth | Hook | Full OIDC context (re-export from react-oidc-context) | | hasAuthParams | Function | Checks if URL has OIDC callback params (re-export) | | AuthContextProps | Type | Type for the useAuth return value (re-export) |

@proyecta-ai/auth/convex-react

| Export | Type | Description | | -------------------------------- | --------- | -------------------------------------------------------- | | ConvexProviderWithProyectaAuth | Component | Authenticated Convex provider using Proyecta OIDC tokens |

Features

• OIDC authorization code flow with PKCE
• Google OAuth and email OTP support
• Convex integration via @proyecta-ai/auth/convex-react
• Configurable OIDC settings via userManagerSettings
• Auth callback hook with timeout, retry, and backend sync support