@ricardoqmd/auth-vue 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ricardoqmd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# @ricardoqmd/auth-vue
+
+> Vue 3 client-side bindings for `@ricardoqmd/auth-core`. A `createAuth` plugin and a reactive `useAuth()` composable with RBAC helpers.
+
+## Installation
+
+```bash
+npm install @ricardoqmd/auth-core @ricardoqmd/auth-keycloak @ricardoqmd/auth-vue vue
+```
+
+> Scope is SPA / client-only (ADR-012). The plugin eagerly initializes the auth
+> flow on install, which assumes a browser. It is SSR-ready by construction (one
+> actor per app instance, never a module-level singleton) but SSR is not a
+> supported target in v0.x.
+
+## Usage
+
+### 1. Create the provider
+
+Create the Keycloak provider **outside** the plugin call so the instance is
+created once. The binding is IDP-agnostic — pass any `AuthProvider`.
+
+```ts
+// src/auth.ts
+import { createKeycloakProvider } from "@ricardoqmd/auth-keycloak";
+
+export const provider = createKeycloakProvider({
+  config: {
+    url: import.meta.env.VITE_KC_URL,
+    realm: import.meta.env.VITE_KC_REALM,
+    clientId: import.meta.env.VITE_KC_CLIENT_ID,
+  },
+});
+```
+
+### 2. Install the plugin
+
+```ts
+// src/main.ts
+import { createApp } from "vue";
+import { createAuth } from "@ricardoqmd/auth-vue";
+import App from "./App.vue";
+import { provider } from "./auth";
+
+createApp(App).use(createAuth({ provider })).mount("#app");
+```
+
+### 3. Use auth state in any component
+
+`useAuth()` returns reactive state. The state values are `ComputedRef`s — read
+them with `.value` in `<script setup>`; in the template they are auto-unwrapped,
+so you can write `isAuthenticated` directly without `.value`.
+
+```vue
+<script setup lang="ts">
+import { useAuth } from "@ricardoqmd/auth-vue";
+import type { KeycloakIdpClaims } from "@ricardoqmd/auth-keycloak";
+
+const { user, isAuthenticated, logout, hasRole, hasAnyRole } =
+  useAuth<KeycloakIdpClaims>();
+
+// In script context, ComputedRefs need .value:
+function reportAdmin() {
+  console.log("is admin?", hasRole("admin"));
+  console.log("authenticated?", isAuthenticated.value);
+}
+</script>
+
+<template>
+  <!-- In templates, refs are auto-unwrapped (no .value): -->
+  <p>Welcome, {{ user?.preferred_username }}</p>
+  <button v-if="hasRole('admin')">Admin panel</button>
+  <button v-if="hasAnyRole(['editor', 'admin'])">Edit</button>
+  <button @click="logout">Sign out</button>
+</template>
+```
+
+`useAuth<TIdpClaims>()` is generic over the IDP claims shape. Pass your adapter's
+claims interface (e.g. `KeycloakIdpClaims`) for typed access to `idpClaims`. For
+the universal role checks, use `hasRole()` / `hasAnyRole()`; for provider-specific
+checks (e.g. Keycloak resource roles), import utilities from your adapter package.
+
+### Sign-in on demand (`check-sso` flows)
+
+When the provider is configured for `check-sso`, the app starts unauthenticated.
+Call `login()` from the composable to start the redirect:
+
+```vue
+<script setup lang="ts">
+import { useAuth } from "@ricardoqmd/auth-vue";
+
+const { isAuthenticated, login, logout } = useAuth();
+</script>
+
+<template>
+  <button v-if="isAuthenticated" @click="logout">Sign out</button>
+  <button v-else @click="login">Sign in</button>
+</template>
+```
+
+### Gating the app while auth settles
+
+There is no built-in `AuthGate` component in v0.x. Gate at the root with `v-if`
+on `isLoading` and `error`, then render your app once auth is settled:
+
+```vue
+<script setup lang="ts">
+import { useAuth } from "@ricardoqmd/auth-vue";
+
+const { isLoading, error, isAuthenticated } = useAuth();
+</script>
+
+<template>
+  <p v-if="isLoading">Signing in…</p>
+  <p v-else-if="error">Authentication failed: {{ error.message }}</p>
+  <RouterView v-else-if="isAuthenticated" />
+  <LoginScreen v-else />
+</template>
+```
+
+## API
+
+### `createAuth(options)`
+
+Returns a Vue `Plugin`. Install with `app.use(createAuth({ provider }))`. Creates
+one auth actor per app instance, starts it, sends `INIT`, and provides it app-wide.
+
+| Option | Type | Description |
+|---|---|---|
+| `provider` | `AuthProvider<TIdpClaims>` | Adapter instance from `createKeycloakProvider()` (or any IDP adapter). Create it once, outside the plugin call. |
+
+### `useAuth<TIdpClaims>()`
+
+Must be called in `setup()` of a component whose app installed `createAuth()`.
+Throws otherwise. Returns an `AuthState<TIdpClaims>`:
+
+| Field | Type | Description |
+|---|---|---|
+| `isLoading` | `ComputedRef<boolean>` | True during `initializing` or `loggingOut` |
+| `isAuthenticated` | `ComputedRef<boolean>` | True when the machine is in the `authenticated` state |
+| `token` | `ComputedRef<string \| null>` | Raw JWT access token |
+| `user` | `ComputedRef<AuthUserClaims \| null>` | Decoded standard OIDC claims (`preferred_username`, `email`, `name`, `sub`, `roles`, …) |
+| `idpClaims` | `ComputedRef<TIdpClaims \| null>` | IDP-specific token claims; pass your IDP's claims interface to `useAuth<T>()` |
+| `error` | `ComputedRef<AuthError \| null>` | Structured error set in the `error` state; branch on `error.code` |
+| `login` | `() => void` | Starts the login redirect (useful with `check-sso`) |
+| `logout` | `() => void` | Triggers the logout flow |
+| `hasRole` | `(role: string) => boolean` | True if `user.roles` includes `role` |
+| `hasAnyRole` | `(roles: string[]) => boolean` | True if the user has at least one of the given roles |
+
+## Handling errors
+
+`error` is a structured `AuthError` from `@ricardoqmd/auth-core`, not a plain
+`Error`. Branch on `error.code` to drive UX. `code` is one of `INIT_FAILED`,
+`REFRESH_FAILED`, `TOKEN_EXPIRED`, or `NETWORK_ERROR`. New codes may be added
+over time, so always handle `default`. (`TOKEN_EXPIRED` is reserved and not
+currently emitted by `auth-keycloak` — a dead refresh token rejects as
+`REFRESH_FAILED`; see ADR-009.)
+
+## Status
+
+**Pre-1.0.** The public API mirrors `@ricardoqmd/auth-nextjs` and shares the
+`@ricardoqmd/auth-core` contract.
+
+## License
+
+MIT © [ricardoqmd](https://github.com/ricardoqmd)

package/dist/index.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+var xstate = require('xstate');
+var authCore = require('@ricardoqmd/auth-core');
+var vue = require('vue');
+var vue$1 = require('@xstate/vue');
+
+// src/plugin.ts
+
+// src/injection-key.ts
+var AUTH_INJECTION_KEY = /* @__PURE__ */ Symbol("ricardoqmd-auth");
+
+// src/plugin.ts
+function createAuth(options) {
+  return {
+    install(app) {
+      const machine = authCore.createAuthMachine(options.provider);
+      const actor = xstate.createActor(machine);
+      actor.start();
+      actor.send({ type: "INIT" });
+      app.provide(AUTH_INJECTION_KEY, actor);
+      const unmountable = app;
+      if (typeof unmountable.onUnmount === "function") {
+        unmountable.onUnmount(() => actor.stop());
+      }
+    }
+  };
+}
+function useAuth() {
+  const actor = vue.inject(AUTH_INJECTION_KEY);
+  if (!actor) {
+    throw new Error(
+      "useAuth() must be called within an app that installed the auth plugin. Did you forget app.use(createAuth({ provider }))?"
+    );
+  }
+  const stateValue = vue$1.useSelector(actor, (s) => s.value);
+  const context = vue$1.useSelector(actor, (s) => s.context);
+  const isAuthenticated = vue.computed(
+    () => typeof stateValue.value === "object" && stateValue.value !== null && "authenticated" in stateValue.value
+  );
+  const topState = vue.computed(
+    () => typeof stateValue.value === "string" ? stateValue.value : Object.keys(stateValue.value)[0]
+  );
+  const isLoading = vue.computed(
+    () => topState.value === "initializing" || topState.value === "loggingOut"
+  );
+  const token = vue.computed(() => context.value.token);
+  const user = vue.computed(() => context.value.user);
+  const idpClaims = vue.computed(() => context.value.idpClaims);
+  const error = vue.computed(() => context.value.error);
+  const login = () => actor.send({ type: "LOGIN" });
+  const logout = () => actor.send({ type: "LOGOUT" });
+  const hasRole = (role) => user.value?.roles?.includes(role) ?? false;
+  const hasAnyRole = (roles) => roles.some((r) => user.value?.roles?.includes(r) ?? false);
+  return {
+    isLoading,
+    isAuthenticated,
+    token,
+    user,
+    idpClaims,
+    error,
+    login,
+    logout,
+    hasRole,
+    hasAnyRole
+  };
+}
+
+exports.createAuth = createAuth;
+exports.useAuth = useAuth;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/injection-key.ts","../src/plugin.ts","../src/composable.ts"],"names":["createAuthMachine","createActor","inject","useSelector","computed"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { InjectionKey } from \"vue\";\nimport type { Actor } from \"xstate\";\nimport type { createAuthMachine } from \"@ricardoqmd/auth-core\";\n\n/** The started auth actor type, derived from the core machine factory. */\nexport type AuthActor<TIdpClaims = unknown> = Actor<\n  ReturnType<typeof createAuthMachine<TIdpClaims>>\n>;\n\n/** App-wide injection key for the auth actor created by the createAuth plugin. */\nexport const AUTH_INJECTION_KEY: InjectionKey<AuthActor> = Symbol(\"ricardoqmd-auth\");\n","import type { App, Plugin } from \"vue\";\nimport { createActor } from \"xstate\";\nimport { createAuthMachine, type AuthProvider } from \"@ricardoqmd/auth-core\";\nimport { AUTH_INJECTION_KEY, type AuthActor } from \"./injection-key.js\";\n\nexport interface CreateAuthOptions<TIdpClaims = unknown> {\n  /** Adapter instance (e.g. createKeycloakProvider()). IDP-agnostic. */\n  provider: AuthProvider<TIdpClaims>;\n}\n\n/**\n * Vue plugin wiring @ricardoqmd/auth-core into a Vue app.\n *\n * Creates ONE auth actor per app instance (SSR-safe: never a module-level\n * singleton), starts it, kicks off initialization, and provides it app-wide\n * for useAuth(). Scope is SPA/client-only (ADR-012): the eager INIT below\n * assumes a browser. SSR-ready by construction (per-app instance) but not\n * SSR-supported.\n */\nexport function createAuth<TIdpClaims = unknown>(\n  options: CreateAuthOptions<TIdpClaims>,\n): Plugin {\n  return {\n    install(app: App) {\n      const machine = createAuthMachine<TIdpClaims>(options.provider);\n      const actor = createActor(machine);\n      actor.start();\n      actor.send({ type: \"INIT\" });\n      app.provide(AUTH_INJECTION_KEY, actor as AuthActor);\n      // Stop the actor when the app unmounts (avoids leaks in tests/HMR).\n      // app.onUnmount requires Vue 3.5+; guard so older runtimes still install.\n      const unmountable = app as App & { onUnmount?: (cb: () => void) => void };\n      if (typeof unmountable.onUnmount === \"function\") {\n        unmountable.onUnmount(() => actor.stop());\n      }\n    },\n  };\n}\n","import { computed, inject, type ComputedRef } from \"vue\";\nimport { useSelector } from \"@xstate/vue\";\nimport type { AuthError, AuthUserClaims } from \"@ricardoqmd/auth-core\";\nimport { AUTH_INJECTION_KEY } from \"./injection-key.js\";\n\n/** Reactive auth state + helpers returned by useAuth(). */\nexport interface AuthState<TIdpClaims = unknown> {\n  isLoading: ComputedRef<boolean>;\n  isAuthenticated: ComputedRef<boolean>;\n  token: ComputedRef<string | null>;\n  user: ComputedRef<AuthUserClaims | null>;\n  idpClaims: ComputedRef<TIdpClaims | null>;\n  error: ComputedRef<AuthError | null>;\n  login: () => void;\n  logout: () => void;\n  hasRole: (role: string) => boolean;\n  hasAnyRole: (roles: string[]) => boolean;\n}\n\n/**\n * Reactive authentication state for the current app.\n * Must be called inside a component of an app that installed createAuth().\n */\nexport function useAuth<TIdpClaims = unknown>(): AuthState<TIdpClaims> {\n  const actor = inject(AUTH_INJECTION_KEY);\n  if (!actor) {\n    throw new Error(\n      \"useAuth() must be called within an app that installed the auth plugin. \" +\n        \"Did you forget app.use(createAuth({ provider }))?\",\n    );\n  }\n\n  const stateValue = useSelector(actor, (s) => s.value);\n  const context = useSelector(actor, (s) => s.context);\n\n  const isAuthenticated = computed(\n    () =>\n      typeof stateValue.value === \"object\" &&\n      stateValue.value !== null &&\n      \"authenticated\" in stateValue.value,\n  );\n\n  const topState = computed(() =>\n    typeof stateValue.value === \"string\"\n      ? stateValue.value\n      : Object.keys(stateValue.value)[0],\n  );\n\n  const isLoading = computed(\n    () => topState.value === \"initializing\" || topState.value === \"loggingOut\",\n  );\n\n  const token = computed(() => context.value.token);\n  const user = computed(() => context.value.user);\n  const idpClaims = computed(() => context.value.idpClaims as TIdpClaims | null);\n  const error = computed(() => context.value.error);\n\n  const login = () => actor.send({ type: \"LOGIN\" });\n  const logout = () => actor.send({ type: \"LOGOUT\" });\n\n  const hasRole = (role: string) =>\n    user.value?.roles?.includes(role) ?? false;\n  const hasAnyRole = (roles: string[]) =>\n    roles.some((r) => user.value?.roles?.includes(r) ?? false);\n\n  return {\n    isLoading,\n    isAuthenticated,\n    token,\n    user,\n    idpClaims,\n    error,\n    login,\n    logout,\n    hasRole,\n    hasAnyRole,\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,43 @@
+import { Plugin, ComputedRef } from 'vue';
+import { AuthProvider, AuthUserClaims, AuthError, createAuthMachine } from '@ricardoqmd/auth-core';
+export { AuthError, AuthInitResult, AuthProvider, AuthTokens, AuthUserClaims, LogoutOptions } from '@ricardoqmd/auth-core';
+import { Actor } from 'xstate';
+
+interface CreateAuthOptions<TIdpClaims = unknown> {
+    /** Adapter instance (e.g. createKeycloakProvider()). IDP-agnostic. */
+    provider: AuthProvider<TIdpClaims>;
+}
+/**
+ * Vue plugin wiring @ricardoqmd/auth-core into a Vue app.
+ *
+ * Creates ONE auth actor per app instance (SSR-safe: never a module-level
+ * singleton), starts it, kicks off initialization, and provides it app-wide
+ * for useAuth(). Scope is SPA/client-only (ADR-012): the eager INIT below
+ * assumes a browser. SSR-ready by construction (per-app instance) but not
+ * SSR-supported.
+ */
+declare function createAuth<TIdpClaims = unknown>(options: CreateAuthOptions<TIdpClaims>): Plugin;
+
+/** Reactive auth state + helpers returned by useAuth(). */
+interface AuthState<TIdpClaims = unknown> {
+    isLoading: ComputedRef<boolean>;
+    isAuthenticated: ComputedRef<boolean>;
+    token: ComputedRef<string | null>;
+    user: ComputedRef<AuthUserClaims | null>;
+    idpClaims: ComputedRef<TIdpClaims | null>;
+    error: ComputedRef<AuthError | null>;
+    login: () => void;
+    logout: () => void;
+    hasRole: (role: string) => boolean;
+    hasAnyRole: (roles: string[]) => boolean;
+}
+/**
+ * Reactive authentication state for the current app.
+ * Must be called inside a component of an app that installed createAuth().
+ */
+declare function useAuth<TIdpClaims = unknown>(): AuthState<TIdpClaims>;
+
+/** The started auth actor type, derived from the core machine factory. */
+type AuthActor<TIdpClaims = unknown> = Actor<ReturnType<typeof createAuthMachine<TIdpClaims>>>;
+
+export { type AuthActor, type AuthState, type CreateAuthOptions, createAuth, useAuth };

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { Plugin, ComputedRef } from 'vue';
+import { AuthProvider, AuthUserClaims, AuthError, createAuthMachine } from '@ricardoqmd/auth-core';
+export { AuthError, AuthInitResult, AuthProvider, AuthTokens, AuthUserClaims, LogoutOptions } from '@ricardoqmd/auth-core';
+import { Actor } from 'xstate';
+
+interface CreateAuthOptions<TIdpClaims = unknown> {
+    /** Adapter instance (e.g. createKeycloakProvider()). IDP-agnostic. */
+    provider: AuthProvider<TIdpClaims>;
+}
+/**
+ * Vue plugin wiring @ricardoqmd/auth-core into a Vue app.
+ *
+ * Creates ONE auth actor per app instance (SSR-safe: never a module-level
+ * singleton), starts it, kicks off initialization, and provides it app-wide
+ * for useAuth(). Scope is SPA/client-only (ADR-012): the eager INIT below
+ * assumes a browser. SSR-ready by construction (per-app instance) but not
+ * SSR-supported.
+ */
+declare function createAuth<TIdpClaims = unknown>(options: CreateAuthOptions<TIdpClaims>): Plugin;
+
+/** Reactive auth state + helpers returned by useAuth(). */
+interface AuthState<TIdpClaims = unknown> {
+    isLoading: ComputedRef<boolean>;
+    isAuthenticated: ComputedRef<boolean>;
+    token: ComputedRef<string | null>;
+    user: ComputedRef<AuthUserClaims | null>;
+    idpClaims: ComputedRef<TIdpClaims | null>;
+    error: ComputedRef<AuthError | null>;
+    login: () => void;
+    logout: () => void;
+    hasRole: (role: string) => boolean;
+    hasAnyRole: (roles: string[]) => boolean;
+}
+/**
+ * Reactive authentication state for the current app.
+ * Must be called inside a component of an app that installed createAuth().
+ */
+declare function useAuth<TIdpClaims = unknown>(): AuthState<TIdpClaims>;
+
+/** The started auth actor type, derived from the core machine factory. */
+type AuthActor<TIdpClaims = unknown> = Actor<ReturnType<typeof createAuthMachine<TIdpClaims>>>;
+
+export { type AuthActor, type AuthState, type CreateAuthOptions, createAuth, useAuth };

package/dist/index.js

@@ -0,0 +1,69 @@
+import { createActor } from 'xstate';
+import { createAuthMachine } from '@ricardoqmd/auth-core';
+import { inject, computed } from 'vue';
+import { useSelector } from '@xstate/vue';
+
+// src/plugin.ts
+
+// src/injection-key.ts
+var AUTH_INJECTION_KEY = /* @__PURE__ */ Symbol("ricardoqmd-auth");
+
+// src/plugin.ts
+function createAuth(options) {
+  return {
+    install(app) {
+      const machine = createAuthMachine(options.provider);
+      const actor = createActor(machine);
+      actor.start();
+      actor.send({ type: "INIT" });
+      app.provide(AUTH_INJECTION_KEY, actor);
+      const unmountable = app;
+      if (typeof unmountable.onUnmount === "function") {
+        unmountable.onUnmount(() => actor.stop());
+      }
+    }
+  };
+}
+function useAuth() {
+  const actor = inject(AUTH_INJECTION_KEY);
+  if (!actor) {
+    throw new Error(
+      "useAuth() must be called within an app that installed the auth plugin. Did you forget app.use(createAuth({ provider }))?"
+    );
+  }
+  const stateValue = useSelector(actor, (s) => s.value);
+  const context = useSelector(actor, (s) => s.context);
+  const isAuthenticated = computed(
+    () => typeof stateValue.value === "object" && stateValue.value !== null && "authenticated" in stateValue.value
+  );
+  const topState = computed(
+    () => typeof stateValue.value === "string" ? stateValue.value : Object.keys(stateValue.value)[0]
+  );
+  const isLoading = computed(
+    () => topState.value === "initializing" || topState.value === "loggingOut"
+  );
+  const token = computed(() => context.value.token);
+  const user = computed(() => context.value.user);
+  const idpClaims = computed(() => context.value.idpClaims);
+  const error = computed(() => context.value.error);
+  const login = () => actor.send({ type: "LOGIN" });
+  const logout = () => actor.send({ type: "LOGOUT" });
+  const hasRole = (role) => user.value?.roles?.includes(role) ?? false;
+  const hasAnyRole = (roles) => roles.some((r) => user.value?.roles?.includes(r) ?? false);
+  return {
+    isLoading,
+    isAuthenticated,
+    token,
+    user,
+    idpClaims,
+    error,
+    login,
+    logout,
+    hasRole,
+    hasAnyRole
+  };
+}
+
+export { createAuth, useAuth };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/injection-key.ts","../src/plugin.ts","../src/composable.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { InjectionKey } from \"vue\";\nimport type { Actor } from \"xstate\";\nimport type { createAuthMachine } from \"@ricardoqmd/auth-core\";\n\n/** The started auth actor type, derived from the core machine factory. */\nexport type AuthActor<TIdpClaims = unknown> = Actor<\n  ReturnType<typeof createAuthMachine<TIdpClaims>>\n>;\n\n/** App-wide injection key for the auth actor created by the createAuth plugin. */\nexport const AUTH_INJECTION_KEY: InjectionKey<AuthActor> = Symbol(\"ricardoqmd-auth\");\n","import type { App, Plugin } from \"vue\";\nimport { createActor } from \"xstate\";\nimport { createAuthMachine, type AuthProvider } from \"@ricardoqmd/auth-core\";\nimport { AUTH_INJECTION_KEY, type AuthActor } from \"./injection-key.js\";\n\nexport interface CreateAuthOptions<TIdpClaims = unknown> {\n  /** Adapter instance (e.g. createKeycloakProvider()). IDP-agnostic. */\n  provider: AuthProvider<TIdpClaims>;\n}\n\n/**\n * Vue plugin wiring @ricardoqmd/auth-core into a Vue app.\n *\n * Creates ONE auth actor per app instance (SSR-safe: never a module-level\n * singleton), starts it, kicks off initialization, and provides it app-wide\n * for useAuth(). Scope is SPA/client-only (ADR-012): the eager INIT below\n * assumes a browser. SSR-ready by construction (per-app instance) but not\n * SSR-supported.\n */\nexport function createAuth<TIdpClaims = unknown>(\n  options: CreateAuthOptions<TIdpClaims>,\n): Plugin {\n  return {\n    install(app: App) {\n      const machine = createAuthMachine<TIdpClaims>(options.provider);\n      const actor = createActor(machine);\n      actor.start();\n      actor.send({ type: \"INIT\" });\n      app.provide(AUTH_INJECTION_KEY, actor as AuthActor);\n      // Stop the actor when the app unmounts (avoids leaks in tests/HMR).\n      // app.onUnmount requires Vue 3.5+; guard so older runtimes still install.\n      const unmountable = app as App & { onUnmount?: (cb: () => void) => void };\n      if (typeof unmountable.onUnmount === \"function\") {\n        unmountable.onUnmount(() => actor.stop());\n      }\n    },\n  };\n}\n","import { computed, inject, type ComputedRef } from \"vue\";\nimport { useSelector } from \"@xstate/vue\";\nimport type { AuthError, AuthUserClaims } from \"@ricardoqmd/auth-core\";\nimport { AUTH_INJECTION_KEY } from \"./injection-key.js\";\n\n/** Reactive auth state + helpers returned by useAuth(). */\nexport interface AuthState<TIdpClaims = unknown> {\n  isLoading: ComputedRef<boolean>;\n  isAuthenticated: ComputedRef<boolean>;\n  token: ComputedRef<string | null>;\n  user: ComputedRef<AuthUserClaims | null>;\n  idpClaims: ComputedRef<TIdpClaims | null>;\n  error: ComputedRef<AuthError | null>;\n  login: () => void;\n  logout: () => void;\n  hasRole: (role: string) => boolean;\n  hasAnyRole: (roles: string[]) => boolean;\n}\n\n/**\n * Reactive authentication state for the current app.\n * Must be called inside a component of an app that installed createAuth().\n */\nexport function useAuth<TIdpClaims = unknown>(): AuthState<TIdpClaims> {\n  const actor = inject(AUTH_INJECTION_KEY);\n  if (!actor) {\n    throw new Error(\n      \"useAuth() must be called within an app that installed the auth plugin. \" +\n        \"Did you forget app.use(createAuth({ provider }))?\",\n    );\n  }\n\n  const stateValue = useSelector(actor, (s) => s.value);\n  const context = useSelector(actor, (s) => s.context);\n\n  const isAuthenticated = computed(\n    () =>\n      typeof stateValue.value === \"object\" &&\n      stateValue.value !== null &&\n      \"authenticated\" in stateValue.value,\n  );\n\n  const topState = computed(() =>\n    typeof stateValue.value === \"string\"\n      ? stateValue.value\n      : Object.keys(stateValue.value)[0],\n  );\n\n  const isLoading = computed(\n    () => topState.value === \"initializing\" || topState.value === \"loggingOut\",\n  );\n\n  const token = computed(() => context.value.token);\n  const user = computed(() => context.value.user);\n  const idpClaims = computed(() => context.value.idpClaims as TIdpClaims | null);\n  const error = computed(() => context.value.error);\n\n  const login = () => actor.send({ type: \"LOGIN\" });\n  const logout = () => actor.send({ type: \"LOGOUT\" });\n\n  const hasRole = (role: string) =>\n    user.value?.roles?.includes(role) ?? false;\n  const hasAnyRole = (roles: string[]) =>\n    roles.some((r) => user.value?.roles?.includes(r) ?? false);\n\n  return {\n    isLoading,\n    isAuthenticated,\n    token,\n    user,\n    idpClaims,\n    error,\n    login,\n    logout,\n    hasRole,\n    hasAnyRole,\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@ricardoqmd/auth-vue",
+  "version": "0.1.0",
+  "description": "Vue 3 client-side bindings for @ricardoqmd/auth-core — createAuth plugin, useAuth composable, RBAC helpers",
+  "keywords": [
+    "auth",
+    "vue",
+    "vue3",
+    "keycloak",
+    "composable",
+    "rbac"
+  ],
+  "author": "ricardoqmd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ricardoqmd/auth.git",
+    "directory": "packages/auth-vue"
+  },
+  "homepage": "https://github.com/ricardoqmd/auth/tree/main/packages/auth-vue",
+  "bugs": "https://github.com/ricardoqmd/auth/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@xstate/vue": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@ricardoqmd/auth-core": "^1.0.0",
+    "vue": "^3.5.0",
+    "xstate": "^5.20.0"
+  },
+  "devDependencies": {
+    "@vue/test-utils": "^2.4.6",
+    "vue": "^3.5.13",
+    "xstate": "^5.20.0",
+    "jsdom": "^29.1.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.5",
+    "@ricardoqmd/auth-core": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo"
+  }
+}