@moreillon/vue-oidc 0.0.14 → 0.1.0

package/README.md

@@ -1,41 +1,85 @@
 # Vue OIDC
 
-## Usage example
+Vue 3 plugin and composable for OpenID Connect authentication, built on [@moreillon/oidc-auth](https://www.npmjs.com/package/@moreillon/oidc-auth).
+
+## Installation
+
+```bash
+npm install @moreillon/vue-oidc
+```
+
+`vue` (^3.5) is a peer dependency.
+
+## Setup
 
 ```ts
 import { createApp } from "vue";
-import { createPinia } from "pinia";
 import { auth } from "@moreillon/vue-oidc";
 import App from "./App.vue";
-import router from "./router";
-
-const app = createApp(App);
 
 const { VITE_OIDC_AUTHORITY, VITE_OIDC_CLIENT_ID } = import.meta.env;
 
-app.use(auth, {
-  authority: VITE_OIDC_AUTHORITY,
-  client_id: VITE_OIDC_CLIENT_ID,
-});
-app.use(createPinia());
-app.use(router);
-
-app.mount("#app");
+createApp(App)
+  .use(auth, {
+    authority: VITE_OIDC_AUTHORITY,
+    client_id: VITE_OIDC_CLIENT_ID,
+  })
+  .mount("#app");
 ```
 
-Then in your components:
+### Options
+
+| Option             | Type                     | Description                                                                      |
+| ------------------ | ------------------------ | -------------------------------------------------------------------------------- |
+| `authority`        | `string`                 | URL of the OIDC provider (required)                                              |
+| `client_id`        | `string`                 | OIDC client ID (required)                                                        |
+| `redirect_uri`     | `string`                 | Where the provider redirects after login. Defaults to the current page           |
+| `extraQueryParams` | `Record<string, string>` | Additional query parameters sent to the authorization endpoint                   |
+| `enforce`          | `boolean`                | Redirect unauthenticated users to the provider immediately instead of letting them in anonymously |
+
+## Usage
+
+Initialization is asynchronous and the app mounts before it finishes, so wait for `ready` before rendering anything that depends on authentication:
 
 ```vue
 <script setup lang="ts">
 import { useAuth } from "@moreillon/vue-oidc";
 
-const { user } = useAuth();
+const { ready, error, user, login, logout } = useAuth();
 </script>
 
 <template>
-  <h1>User</h1>
-  <p>
-    {{ user }}
-  </p>
+  <p v-if="!ready">Loading...</p>
+  <p v-else-if="error">Authentication failed: {{ error }}</p>
+  <template v-else-if="user">
+    <p>Hello {{ user.name }}</p>
+    <button @click="logout">Log out</button>
+  </template>
+  <button v-else @click="login">Log in</button>
 </template>
 ```
+
+### `useAuth()`
+
+All refs are read-only.
+
+| Property       | Type                              | Description                                                                 |
+| -------------- | --------------------------------- | --------------------------------------------------------------------------- |
+| `ready`        | `Ref<boolean>`                    | `true` once initialization has finished (successfully or not)               |
+| `error`        | `Ref<unknown>`                    | Error thrown during initialization, if any                                  |
+| `user`         | `Ref<User \| null>`               | User info of the authenticated user                                         |
+| `access_token` | `Ref<string \| null>`             | Current access token, kept up to date on refresh                            |
+| `client`       | `Ref<OidcClient \| null>`         | Underlying `@moreillon/oidc-auth` client                                    |
+| `login()`      | `() => void`                      | Redirect to the provider's login page                                       |
+| `logout()`     | `() => void`                      | Log out at the provider                                                     |
+
+`useAuth` accepts a type parameter for custom claims: `useAuth<MyUser>()`.
+
+The state is shared at module level, so `useAuth()` also works outside components, e.g. in router guards or API clients:
+
+```ts
+const { access_token } = useAuth();
+fetch("/api/items", {
+  headers: { Authorization: `Bearer ${access_token.value}` },
+});
+```

package/dist/composables/useAuth.d.ts

@@ -1,81 +1,33 @@
 import type OidcClient from "@moreillon/oidc-auth";
-declare function login(): void;
-declare function logout(): void;
-export default function (): {
-    ready: import("vue").Ref<boolean, boolean>;
-    client: import("vue").Ref<{
-        cookieName: string;
-        options: {
-            redirect_uri: string;
-            authority: string;
-            client_id: string;
-            extraQueryParams?: {
-                [key: string]: string;
-            } | undefined;
-        };
-        openidConfig?: {
-            authorization_endpoint: string;
-            token_endpoint: string;
-            userinfo_endpoint: string;
-            end_session_endpoint: string;
-        } | undefined;
-        refreshEventHandlers: Function[];
-        init: (enforce?: boolean) => Promise<import("@moreillon/oidc-auth").InitOutput | undefined>;
-        sendUserToAuthUrl: (saveHref: Boolean) => Promise<void>;
-        fetchOidcConfig: () => Promise<any>;
-        generateAuthUrl: () => Promise<string>;
-        createTimeoutForTokenExpiry: (oidConfig: import("@moreillon/oidc-auth").OidcConfig) => void;
-        makeCookieOptions: () => string;
-        makeExpiryDate: (expires_in: number) => Date;
-        isExpired: (expires_at: string) => boolean;
-        saveAuthDataInCookies: (data: {
-            expires_in: number;
-        }) => void;
-        exchangeCodeForToken: (code: string) => Promise<void>;
-        getUser: () => Promise<any>;
-        refreshAccessToken: (oidcConfig: import("@moreillon/oidc-auth").OidcConfig) => Promise<void>;
-        onTokenRefreshed: (handler: (oidcData: import("@moreillon/oidc-auth").Tokens) => void) => void;
-        runRefreshEventHandlers: () => void;
-        login: () => void;
-        logout: () => void;
-    } | null, OidcClient | {
-        cookieName: string;
-        options: {
-            redirect_uri: string;
-            authority: string;
-            client_id: string;
-            extraQueryParams?: {
-                [key: string]: string;
-            } | undefined;
-        };
-        openidConfig?: {
-            authorization_endpoint: string;
-            token_endpoint: string;
-            userinfo_endpoint: string;
-            end_session_endpoint: string;
-        } | undefined;
-        refreshEventHandlers: Function[];
-        init: (enforce?: boolean) => Promise<import("@moreillon/oidc-auth").InitOutput | undefined>;
-        sendUserToAuthUrl: (saveHref: Boolean) => Promise<void>;
-        fetchOidcConfig: () => Promise<any>;
-        generateAuthUrl: () => Promise<string>;
-        createTimeoutForTokenExpiry: (oidConfig: import("@moreillon/oidc-auth").OidcConfig) => void;
-        makeCookieOptions: () => string;
-        makeExpiryDate: (expires_in: number) => Date;
-        isExpired: (expires_at: string) => boolean;
-        saveAuthDataInCookies: (data: {
-            expires_in: number;
-        }) => void;
-        exchangeCodeForToken: (code: string) => Promise<void>;
-        getUser: () => Promise<any>;
-        refreshAccessToken: (oidcConfig: import("@moreillon/oidc-auth").OidcConfig) => Promise<void>;
-        onTokenRefreshed: (handler: (oidcData: import("@moreillon/oidc-auth").Tokens) => void) => void;
-        runRefreshEventHandlers: () => void;
-        login: () => void;
-        logout: () => void;
+import type { User } from "@moreillon/oidc-auth";
+export declare const state: {
+    client: import("vue").ShallowRef<OidcClient | null, OidcClient | null>;
+    user: import("vue").Ref<{
+        [x: string]: unknown;
+        name: string;
+        email: string;
+        family_name: string;
+        given_name: string;
+    } | null, User | {
+        [x: string]: unknown;
+        name: string;
+        email: string;
+        family_name: string;
+        given_name: string;
     } | null>;
-    user: import("vue").Ref<any, any>;
     access_token: import("vue").Ref<string | null, string | null>;
+    ready: import("vue").Ref<boolean, boolean>;
+    error: import("vue").ShallowRef<unknown, unknown>;
+};
+export declare function resetState(): void;
+declare function login(): void;
+declare function logout(): void;
+export default function useAuth<T extends User = User>(): {
+    ready: Readonly<import("vue").Ref<boolean, boolean>>;
+    error: import("vue").ComputedRef<unknown>;
+    client: import("vue").ComputedRef<OidcClient | null>;
+    user: import("vue").ComputedRef<T | null>;
+    access_token: Readonly<import("vue").Ref<string | null, string | null>>;
     login: typeof login;
     logout: typeof logout;
 };

package/dist/composables/useAuth.js

@@ -1,24 +1,38 @@
-import { ref } from "vue";
-const client = ref(null);
-const user = ref(null);
-const access_token = ref(null);
-const ready = ref(false);
+import { computed, readonly, ref, shallowRef } from "vue";
+// Module-level state so that useAuth() also works outside of components
+// (e.g. in router navigation guards). Only the plugin may write to it.
+export const state = {
+    client: shallowRef(null),
+    user: ref(null),
+    access_token: ref(null),
+    ready: ref(false),
+    error: shallowRef(null),
+};
+export function resetState() {
+    state.client.value = null;
+    state.user.value = null;
+    state.access_token.value = null;
+    state.ready.value = false;
+    state.error.value = null;
+}
+function getClient() {
+    if (!state.client.value)
+        throw new Error("OIDC Client not instantiated");
+    return state.client.value;
+}
 function login() {
-    if (!client.value)
-        throw new Error("OIDC Client not instanciated");
-    client.value.login();
+    getClient().login();
 }
 function logout() {
-    if (!client.value)
-        throw new Error("OIDC Client not instanciated");
-    client.value.logout();
+    getClient().logout();
 }
-export default function () {
+export default function useAuth() {
     return {
-        ready,
-        client,
-        user,
-        access_token,
+        ready: readonly(state.ready),
+        error: computed(() => state.error.value),
+        client: computed(() => state.client.value),
+        user: computed(() => state.user.value),
+        access_token: readonly(state.access_token),
         login,
         logout,
     };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
-import auth from "./plugins/auth";
-import useAuth from "./composables/useAuth";
+import auth from "./plugins/auth.js";
+import useAuth from "./composables/useAuth.js";
 export { auth, useAuth };
+export type { Options } from "./plugins/auth.js";
+export type { User, Tokens } from "@moreillon/oidc-auth";

package/dist/index.js

@@ -1,3 +1,3 @@
-import auth from "./plugins/auth";
-import useAuth from "./composables/useAuth";
+import auth from "./plugins/auth.js";
+import useAuth from "./composables/useAuth.js";
 export { auth, useAuth };

package/dist/plugins/auth.d.ts

@@ -1,14 +1,9 @@
 import type { App } from "vue";
-export type Options = {
-    authority: string;
-    client_id: string;
-    extraQueryParams?: {
-        [key: string]: string;
-    };
-    redirect_uri?: string;
+import type { UserProvidedOptions } from "@moreillon/oidc-auth";
+export type Options = UserProvidedOptions & {
     enforce?: boolean;
 };
 declare const _default: {
-    install(app: App, options: Options): Promise<void>;
+    install(_app: App, options: Options): Promise<void>;
 };
 export default _default;

package/dist/plugins/auth.js

@@ -1,20 +1,32 @@
-import useAuth from "../composables/useAuth";
 import OidcClient from "@moreillon/oidc-auth";
-export default {
-    async install(app, options) {
-        const { enforce, ...oidcOptions } = options;
-        const auth = useAuth();
-        auth.client.value = new OidcClient(oidcOptions);
-        const oidcData = await auth.client.value.init(enforce);
+import { resetState, state } from "../composables/useAuth.js";
+async function init(options) {
+    const { enforce, ...oidcOptions } = options;
+    resetState();
+    try {
+        const client = new OidcClient(oidcOptions);
+        state.client.value = client;
+        const oidcData = await client.init(enforce);
+        if (oidcData) {
+            state.access_token.value = oidcData.tokens.access_token;
+            state.user.value = oidcData.user;
+            client.onTokenRefreshed(({ access_token }) => {
+                state.access_token.value = access_token;
+            });
+        }
+        // When enforced without data, the user is being redirected to the provider
         if (!enforce || oidcData)
-            auth.ready.value = true;
-        if (!oidcData)
-            return;
-        const { user, tokens: { access_token }, } = oidcData;
-        auth.user.value = user;
-        auth.access_token.value = access_token;
-        auth.client.value.onTokenRefreshed(({ access_token }) => {
-            auth.access_token.value = access_token;
-        });
+            state.ready.value = true;
+    }
+    catch (error) {
+        state.error.value = error;
+        state.ready.value = true;
+    }
+}
+export default {
+    // Vue does not await plugin installation: returned promise is for tests / callers
+    // who want to wait. Apps should rely on the `ready` ref from useAuth().
+    install(_app, options) {
+        return init(options);
     },
 };

package/package.json

@@ -1,28 +1,31 @@
 {
   "name": "@moreillon/vue-oidc",
-  "version": "0.0.14",
+  "version": "0.1.0",
   "type": "module",
   "files": [
     "dist"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
   },
   "dependencies": {
-    "@moreillon/oidc-auth": "^3.0.5",
-    "vue": "^3.5.17"
+    "@moreillon/oidc-auth": "^3.0.6"
   },
   "devDependencies": {
-    "@tsconfig/node22": "^22.0.2",
-    "@types/node": "^22.15.32",
-    "@vitejs/plugin-vue": "^6.0.0",
-    "@vue/tsconfig": "^0.7.0",
-    "npm-run-all2": "^8.0.4",
     "typescript": "~5.8.0",
-    "vite": "^7.0.0",
-    "vite-plugin-vue-devtools": "^7.7.7",
-    "vue-tsc": "^2.2.10"
+    "vitest": "^4.1.12",
+    "vue": "^3.5.44"
   }
 }