npm package: @hemia/access-manager
Description: Vue 3 SDK for handling SSO sessions and permission-based access via @hemia/auth-sso and @hemia/access-sdk.
Author: Hemia Technologies
Latest version: 0.0.5

# @hemia/access-manager

SDK compatible con Vue 3 para el manejo de sesiones SSO y control de acceso basado en permisos. Construido sobre `@hemia/auth-sso` y `@hemia/access-sdk`, este paquete proporciona un plugin instalable y un guard de rutas para facilitar flujos de autenticación y autorización en aplicaciones frontend.

---

## 🚀 Características

* Plugin Vue 3 listo para usar
* Validación de sesión SSO con soporte PKCE y refresh token
* Restauración automática del contexto desde `sessionStorage`
* Verificación de permisos basada en roles, acciones y módulos
* Directiva `v-access` para controlar visibilidad de UI
* Guard global de rutas con soporte para loader

---

## 📦 Instalación

```bash
npm install @hemia/access-manager
```

---

## 🔧 Uso

### 1. Registrar en `main.ts`

```ts
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { createAccessSession, createAccessGuard } from '@hemia/access-manager';

const accessConfig = {
  sso: {
    clientId: '...',
    redirectUri: '...',
    ssoAuthUrl: '...',
    tokenEndpoint: '...',
    scopes: ['openid'],
    sessionEndpoint: '...',
    refreshEndpoint: '...',
    logoutEndpoint: '...',
    logoutRedirectUrl: '...',
    apiKey: '...',
    isDevMode: true
  },
  access: {
    meEndpoint: '/auth/me',
    system: 'hemia-core'
  },
  showLoader: true
};

router.beforeEach(createAccessGuard(accessConfig));

createApp(App)
  .use(createAccessSession(accessConfig))
  .use(router)
  .mount('#app');
```

### 2. Escuchar eventos del loader (opcional)

```vue
<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
const loading = ref(false);

onMounted(() => {
  window.addEventListener('hemia:loader', e => (loading.value = e.detail));
});

onUnmounted(() => {
  window.removeEventListener('hemia:loader', () => {});
});
</script>

<template>
  <g-loader v-if="loading" />
  <router-view />
</template>
```

---

## 🧩 APIs

### Plugin

* `createAccessSession(config: ManagerOptions)`

### Route Guard

* `createAccessGuard(config: ManagerOptions)`

### Composables

* `useSSO()` — acceso a métodos SSO como `startLogin`, `handleCallback`, `logout`, etc.
* `useAccess()` — verificación de permisos vía `hasPermission`, `canAnyOf`, `canAllOf`, etc.

### Directivas

* `v-access` (proporcionada por `@hemia/access-sdk`)

---

## 📚 Tipos

```ts
interface ManagerOptions {
  sso: SSOConfig;
  access: AccessSDKOptions;
}

interface SSOConfig {
  clientId: string;
  redirectUri: string;
  ssoAuthUrl: string;
  tokenEndpoint: string;
  scopes: string[];
  sessionEndpoint: string;
  apiKey?: string;
  refreshEndpoint?: string;
  logoutEndpoint?: string;
  logoutRedirectUrl?: string;
  isDevMode?: boolean;
}

interface Permission {
  type: string;
  actions: string[];
  deniedActions?: string[];
}

interface Role {
  name: string;
  permissions: Permission[];
}

interface UserContext {
  userId: string;
  authId: string;
  globalRoles: Role[];
  systemScopedRoles: Record<string, Role[]>;
  attributes?: Record<string, any>;
  profile?: Record<string, any>;
  meta?: Record<string, any>;
}

interface PermissionCheck {
  type: string;
  action: string;
}

interface AccessSDKOptions {
  meEndpoint: string;
  system: string;
}
```

---

## 📝 Licencia

MIT