@uva-fnwi/datanose-core 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# @uva-fnwi/datanose-core
+
+Shared authentication library for DataNose applications. Provides an OIDC-based auth flow (via `oidc-client-ts`) with support for both SURFconext and Canvas LTI providers.
+
+## What it provides
+
+- **`AuthProvider`** — React context provider that initialises authentication and exposes auth methods via context.
+- **`useAuth`** — Hook to access the auth context from any child component.
+- **`AuthService`** — Lower-level class for apps that manage auth state themselves (e.g. with Redux).
+- **`authReducer`** — Redux-compatible reducer for auth state.
+- **Selectors** — `selectAuthUser`, `selectAuthStatus`, `selectAuthProviderType`, `selectIsAuthenticated`.
+- **Helpers** — `isEmbedded`, `isEmbeddedInCanvas`, `isImpersonating`, `getDataFromToken`, `getUserAndMetadataForCanvasToken`, `getCanvasTokenFromLocalStorage`, `setCanvasTokenInLocalStorage`, `convertUserToObject`, `isUserAuthenticated`.
+- **Types** — `AuthConfig`, `AuthState`, `AuthEventCallbacks`, `ProviderType`, `CustomUserState`.
+
+## Installation
+
+```bash
+npm install @uva-fnwi/datanose-core
+# or
+pnpm add @uva-fnwi/datanose-core
+```
+
+### As a pnpm workspace dependency (monorepo)
+
+```json
+"dependencies": {
+  "@uva-fnwi/datanose-core": "workspace:*"
+}
+```
+
+## Usage
+
+### Option 1: `AuthProvider` + `useAuth` (recommended for React apps)
+
+Wrap your app with `AuthProvider` and access auth state with `useAuth` in any child:
+
+```tsx
+import {AuthProvider, useAuth} from "@uva-fnwi/datanose-core";
+
+const config = {
+    authority: import.meta.env.VITE_AUTH_AUTHORITY,
+    clientId: import.meta.env.VITE_AUTH_CLIENT_ID,
+    redirectUri: window.location.origin,
+    logoutUri: import.meta.env.VITE_AUTH_LOGOUT_URL,
+};
+
+function App() {
+    return (
+        <AuthProvider config={config} events={{}}>
+            <Main />
+        </AuthProvider>
+    );
+}
+
+function Main() {
+    const {isAuthenticated, user, surfStartLogin, surfLogout} = useAuth();
+
+    if (!isAuthenticated) {
+        return <button onClick={() => surfStartLogin(undefined)}>Log in</button>;
+    }
+
+    return (
+        <div>
+            <p>Hello, {user?.profile.name}</p>
+            <button onClick={surfLogout}>Log out</button>
+        </div>
+    );
+}
+```
+
+### Option 2: `AuthService` + `authReducer` (for Redux-based apps)
+
+Use this when you want auth state in your Redux store:
+
+```ts
+import {authReducer, AuthService, selectIsAuthenticated} from "@uva-fnwi/datanose-core";
+import {configureStore} from "@reduxjs/toolkit";
+
+export const store = configureStore({
+    reducer: {
+        auth: authReducer,
+        // ... other reducers
+    },
+});
+
+export const authClient = new AuthService({
+    authority: import.meta.env.VITE_AUTH_AUTHORITY,
+    clientId: import.meta.env.VITE_AUTH_CLIENT_ID,
+    redirectUri: window.location.origin,
+    logoutUri: import.meta.env.VITE_AUTH_LOGOUT_URL,
+});
+
+// Initialise on app start
+await authClient.initialize((action) => store.dispatch(action), {
+    onUserLoaded: (user) => console.log("User loaded", user),
+});
+
+// Read state via selectors
+const isAuthenticated = selectIsAuthenticated(store.getState().auth);
+```
+
+## API reference
+
+### `AuthProvider`
+
+| Prop       | Type                 | Description                                                       |
+| ---------- | -------------------- | ----------------------------------------------------------------- |
+| `config`   | `AuthConfig`         | OIDC configuration (authority, clientId, redirectUri, logoutUri?) |
+| `events`   | `AuthEventCallbacks` | Optional OIDC event callbacks                                     |
+| `children` | `ReactNode`          | —                                                                 |
+
+### `AuthConfig`
+
+```ts
+type AuthConfig = {
+    authority: string;
+    clientId: string;
+    redirectUri: string;
+    logoutUri?: string;
+};
+```
+
+### `useAuth`
+
+Returns `AuthContextProps` (extends `AuthState` with all auth methods). Throws if called outside `<AuthProvider>`.
+
+### Selectors
+
+All selectors take an `AuthState` slice as argument (not the full Redux root state):
+
+```ts
+selectAuthUser(state); // User | null
+selectAuthStatus(state); // "pending" | "fulfilled"
+selectAuthProviderType(state); // ProviderType | null
+selectIsAuthenticated(state); // boolean
+```
+
+## Release process
+
+1. Bump `version` in `packages/core/package.json`
+2. Commit and push to `main`
+3. Create and push a git tag matching the new version:
+    ```bash
+    git tag packages/core@1.x.x
+    git push origin packages/core@1.x.x
+    ```
+4. The GitHub Actions publish workflow triggers automatically: it runs tests, builds the package, and publishes to npm.
+5. Consumers update via:
+    ```bash
+    pnpm add @uva-fnwi/datanose-core@latest
+    ```

package/dist/Auth.helpers.d.ts

@@ -0,0 +1,38 @@
+import { User } from 'oidc-client-ts';
+import { CanvasUserAndMetadata } from './Auth.types';
+/**
+ * Fetch the data part contained within a JWT.
+ */
+export declare const getDataFromToken: <T>(token: string) => T | null;
+/**
+ * Check if a user is authenticated.
+ */
+export declare const isUserAuthenticated: (user: User | null) => boolean;
+/**
+ * Checks if the application is embedded.
+ */
+export declare const isEmbedded: () => boolean;
+/**
+ * Checks if the application is embedded in Canvas.
+ */
+export declare const isEmbeddedInCanvas: () => boolean;
+/**
+ * Takes a Canvas token and uses it to build a new User object and return additional metadata.
+ */
+export declare const getUserAndMetadataForCanvasToken: (token: string) => CanvasUserAndMetadata;
+/**
+ * Get the Canvas token from a separate section of the local storage (non-OIDC).
+ */
+export declare const getCanvasTokenFromLocalStorage: () => string | null;
+/**
+ * Set the Canvas token in a separate section of the local storage (non-OIDC).
+ */
+export declare const setCanvasTokenInLocalStorage: (token: string) => void;
+/**
+ * Convert the User object to a regular object so it can be stored.
+ */
+export declare const convertUserToObject: (user: User | null) => User | null;
+/**
+ * Checks if the current user is actually someone impersonating another user.
+ */
+export declare const isImpersonating: (user: User | null) => boolean;

package/dist/Auth.helpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Auth.reducer.d.ts

@@ -0,0 +1,15 @@
+import { User } from 'oidc-client-ts';
+import { AuthState } from './Auth.state';
+import { ProviderType } from './Auth.types';
+type UnknownAction = {
+    type: string;
+};
+export type AuthAction = {
+    type: "auth/INITIALIZED" | "auth/USER_LOADED";
+    user: User | null;
+    providerType: ProviderType | null;
+} | {
+    type: "auth/LOGOUT" | "auth/USER_UNLOADED" | "auth/LOGGING_OUT";
+};
+export declare function authReducer(state: AuthState | undefined, action: UnknownAction): AuthState;
+export {};

package/dist/Auth.reducer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Auth.selectors.d.ts

@@ -0,0 +1,5 @@
+import { AuthState } from './Auth.state';
+export declare const selectAuthUser: (state: AuthState) => import('oidc-client-ts').User | null;
+export declare const selectAuthStatus: (state: AuthState) => "pending" | "fulfilled";
+export declare const selectAuthProviderType: (state: AuthState) => import('./Auth.types').ProviderType | null;
+export declare const selectIsAuthenticated: (state: AuthState) => boolean;

package/dist/Auth.selectors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Auth.state.d.ts

@@ -0,0 +1,10 @@
+import { User } from 'oidc-client-ts';
+import { ProviderType } from './Auth.types';
+export type AuthState = {
+    user: User | null;
+    providerType: ProviderType | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    isLoggingOut: boolean;
+};
+export declare const DefaultAuthState: AuthState;

package/dist/Auth.types.d.ts

@@ -0,0 +1,60 @@
+import { User } from 'oidc-client-ts';
+import { AuthAction } from './Auth.reducer';
+export type AuthConfig = {
+    authority: string;
+    clientId: string;
+    redirectUri: string;
+    logoutUri?: string;
+};
+export type ProviderType = "surf" | "canvas";
+export type CustomUserState = {
+    redirectUrl: string;
+} | undefined;
+type JwtReservedClaims = {
+    exp: number;
+    iat: number;
+    iss: string;
+    nbf: number;
+};
+export type CanvasToken = JwtReservedClaims & {
+    familyname: string;
+    givenname: string;
+    iss: "lti";
+    name: string;
+    personid: number;
+    role: string;
+    target: string;
+    uvanetid: string;
+    locale: string;
+};
+export type DataNoseToken = JwtReservedClaims & {
+    clientid: string;
+    courseid: string;
+    familyname: string;
+    givenname: string;
+    impersonatedid: string;
+    iss: "dn";
+    name: string;
+    personid: string;
+    role: string;
+    sourcedid: string;
+    studentid: string;
+    uvanetid: string;
+};
+export type CanvasUserAndMetadata = {
+    user: User;
+    target: string;
+    locale: string;
+};
+export type AuthEventCallbacks = {
+    onAccessTokenExpired?: () => void;
+    onAccessTokenExpiring?: () => void;
+    onSilentRenewError?: (error: Error) => void;
+    onUserLoaded?: (user: User) => void;
+    onUserSessionChanged?: () => void;
+    onUserSignedIn?: () => void;
+    onUserSignedOut?: () => void;
+    onUserUnloaded?: () => void;
+};
+export type AuthStateChangeCallback = (action: AuthAction) => void;
+export {};

package/dist/AuthContext.d.ts

@@ -0,0 +1,15 @@
+import { User } from 'oidc-client-ts';
+import { AuthState } from './Auth.state';
+import { CanvasUserAndMetadata, CustomUserState } from './Auth.types';
+export interface AuthContextProps extends AuthState {
+    surfStartLogin(state: CustomUserState): Promise<void>;
+    surfCompleteLogin(): Promise<User>;
+    canvasCompleteLogin(token: string): CanvasUserAndMetadata;
+    surfRenewLogin(state: CustomUserState): Promise<void>;
+    surfLogout(): Promise<void>;
+    impersonateSurfUser(accessToken: string): Promise<void>;
+}
+/**
+ * Context state to store auth data and expose auth functionality.
+ */
+export declare const AuthContext: import('react').Context<AuthContextProps | undefined>;

package/dist/AuthProvider.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { AuthConfig, AuthEventCallbacks } from './Auth.types';
+type AuthProviderProps = {
+    children?: React.ReactNode;
+    config: AuthConfig;
+    events: AuthEventCallbacks;
+};
+/**
+ * Wrapper component that initializes the authentication flow and creates an auth context that can be accessed through useAuth().
+ */
+export declare const AuthProvider: (props: AuthProviderProps) => React.JSX.Element;
+export {};

package/dist/AuthService.d.ts

@@ -0,0 +1,20 @@
+import { User } from 'oidc-client-ts';
+import { AuthConfig, AuthEventCallbacks, AuthStateChangeCallback, CustomUserState } from './Auth.types';
+declare class AuthService {
+    private initialized;
+    private loginInProgress;
+    private logoutUri?;
+    private updateState?;
+    private userManager;
+    constructor(config: AuthConfig);
+    initialize(updateState: AuthStateChangeCallback, events: AuthEventCallbacks): Promise<void>;
+    surfStartLogin: (state: CustomUserState) => Promise<void>;
+    surfCompleteLogin: () => Promise<User>;
+    canvasCompleteLogin: (token: string) => import('./Auth.types').CanvasUserAndMetadata;
+    surfRenewLogin: (state: CustomUserState) => Promise<void>;
+    surfLogout: () => Promise<void>;
+    impersonateSurfUser: (accessToken: string) => Promise<void>;
+    private initCanvasUser;
+    private initEvents;
+}
+export default AuthService;