@seifer-webapp-factory/authorization 0.1.0

package/frontend/templates/pages/roles-list.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+/**
+ * US-Z0204 — Roles-list-pagina (surface, gematerialiseerd, mag divergeren). Toont de rollen via de
+ * pinned `useRoles`-composable (mechanism) over de getypte contract-client (US-Z0105) tegen
+ * `GET /authz/roles`. De hele beheer-surface is gegate met `<Can permission="authz.manage">`
+ * (mechanism, default-deny aan de UI-kant, US-Z0405/US-Z0701): een subject zonder de beheer-
+ * permissie ziet de lijst en de "nieuwe rol"-affordance niet — en er lekt geen tekst of route die
+ * het bestaan ervan verraadt (no-catalog-leak, US-Z0703). Serverfouten uit de taxonomie (US-Z0102)
+ * worden via i18n vertaald en in een `aria-live`-regio getoond. Geen eigen transport.
+ */
+import { onMounted } from 'vue';
+import { Can } from '../../src/index.js';
+import { useRoles } from '../../src/composables.js';
+import { useTranslate } from '../runtime.js';
+
+const t = useTranslate();
+const roles = useRoles();
+
+onMounted(async () => {
+  await roles.refresh();
+});
+</script>
+
+<template>
+  <Can permission="authz.manage">
+    <section class="authz-page authz-page--roles-list">
+      <header class="authz-page__header">
+        <h1 class="authz-page__title">{{ t('authz.roles.title') }}</h1>
+        <p class="authz-page__subtitle">{{ t('authz.roles.subtitle') }}</p>
+        <a class="authz-page__action" href="/admin/roles/new" data-testid="authz-roles-new">
+          {{ t('authz.roles.new') }}
+        </a>
+      </header>
+
+      <p
+        v-if="roles.error.value !== null"
+        class="authz-page__error"
+        role="alert"
+        aria-live="assertive"
+        data-testid="authz-roles-error"
+      >
+        {{ t(roles.error.value) }}
+      </p>
+
+      <p v-if="roles.pending.value" class="authz-page__status" role="status" aria-live="polite">
+        {{ t('authz.roles.loading') }}
+      </p>
+
+      <p v-else-if="roles.roles.value.length === 0" class="authz-page__empty">
+        {{ t('authz.roles.empty') }}
+      </p>
+
+      <table v-else class="authz-roles__table">
+        <thead>
+          <tr>
+            <th scope="col">{{ t('authz.roles.colKey') }}</th>
+            <th scope="col">{{ t('authz.roles.colName') }}</th>
+            <th scope="col">{{ t('authz.roles.colPermissions') }}</th>
+            <th scope="col">{{ t('authz.roles.colParent') }}</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="role in roles.roles.value" :key="role.id" class="authz-roles__row">
+            <th scope="row"><code>{{ role.key }}</code></th>
+            <td>
+              <a :href="`/admin/roles/${role.id}`">{{ role.name }}</a>
+            </td>
+            <td>
+              <span v-if="role.permissions.length === 0" class="authz-roles__muted">
+                {{ t('authz.roles.noPermissions') }}
+              </span>
+              <ul v-else class="authz-roles__permissions">
+                <li v-for="permission in role.permissions" :key="permission">
+                  <code>{{ permission }}</code>
+                </li>
+              </ul>
+            </td>
+            <td>{{ role.parentRoleId ?? t('authz.roles.noParent') }}</td>
+          </tr>
+        </tbody>
+      </table>
+    </section>
+  </Can>
+</template>

package/frontend/templates/plugins/authz.client.ts

@@ -0,0 +1,108 @@
+/**
+ * US-Z0405/US-Z0503 — Authz-bootstrap-plugin (surface, gematerialiseerd, Nuxt client-plugin). Bindt
+ * de frontend-kits en het mechanisme samen tot één per-app-instance geheel — géén module-globale
+ * mutable state:
+ *
+ *  1. `createHttpClient` met een `fetchTransport` die cookies meestuurt (`credentials: 'include'`),
+ *     zodat de auth-sessie/CSRF-cookies automatisch meereizen (module→module op authentication).
+ *  2. `createAuthzClient` (het mechanisme) rond die http-client → `provideAuthzClient`.
+ *  3. De permissie-hydratie + evaluator: `usePermissions().reload()` haalt de effectieve permissies
+ *     uit `/authz/me/permissions` (US-Z0405); een `claimsPermissionSource` leest die reactief uit en
+ *     voedt een `createPermissionEvaluator` die via `providePermissions` de gating aandrijft
+ *     (`<Can>`/`v-can`/`permissionGuard` — deny-by-default, US-Z0701).
+ *  4. i18n-, notifications- en navigate-providers voor de surface-pagina's.
+ *
+ * Dit bestand is een template dat in de host-Nuxt-app wordt gematerialiseerd; het draait niet in de
+ * vitest-render-tests (die injecteren een fake client + evaluator rechtstreeks).
+ */
+import { createHttpClient, fetchTransport } from '@seifer-webapp-factory/kits/frontend/http-client';
+import {
+  createNotifications,
+  systemClock as notifyClock,
+  realScheduler as notifyScheduler,
+} from '@seifer-webapp-factory/kits/frontend/notifications';
+import { provideNotifications } from '@seifer-webapp-factory/kits/frontend/notifications/vue';
+import { createI18n, provideI18n } from '@seifer-webapp-factory/kits/frontend/i18n/vue';
+import { staticCatalogLoader } from '@seifer-webapp-factory/kits/frontend/i18n';
+import { createAuthzClient } from '../../src/index.js';
+import {
+  provideAuthzClient,
+  usePermissions,
+} from '../../src/composables.js';
+import {
+  claimsPermissionSource,
+  createPermissionEvaluator,
+  providePermissions,
+} from '../../src/index.js';
+import { provideNavigate } from '../runtime.js';
+import nl from '../i18n/nl.json';
+import en from '../i18n/en.json';
+
+// `defineNuxtPlugin`, `navigateTo`, `useRuntimeConfig` zijn Nuxt auto-imports (host-context).
+declare const defineNuxtPlugin: <T>(setup: (nuxtApp: NuxtAppLike) => T) => unknown;
+declare const navigateTo: (to: string) => unknown;
+declare const useRuntimeConfig: () => { public?: { authzBaseUrl?: string } };
+
+interface NuxtAppLike {
+  readonly vueApp: import('vue').App;
+  provide(name: string, value: unknown): void;
+}
+
+export default defineNuxtPlugin(async (nuxtApp) => {
+  const app = nuxtApp.vueApp;
+
+  // 1. HTTP-client met cookie-transport (auth-sessie + CSRF via httpOnly-cookies reizen mee).
+  const baseUrl = useRuntimeConfig().public?.authzBaseUrl ?? '/api';
+  const credentialledFetch: typeof fetch = (input, init) =>
+    fetch(input, { ...init, credentials: 'include' });
+  const http = createHttpClient({
+    transport: fetchTransport(credentialledFetch),
+    baseUrl,
+    defaultHeaders: { accept: 'application/json' },
+  });
+
+  // 2. Het mechanisme: de getypte authorization-client.
+  const client = createAuthzClient({ http });
+  provideAuthzClient(app, client);
+
+  // 3. Permissie-hydratie + de deny-by-default evaluator die de gating aandrijft. `usePermissions`
+  //    en `providePermissions` draaien binnen de app-context zodat `inject` de client vindt.
+  await app.runWithContext(async () => {
+    const permissions = usePermissions();
+    const evaluator = createPermissionEvaluator(
+      claimsPermissionSource(() => ({
+        roles: permissions.roles.value,
+        permissions: permissions.permissions.value,
+      })),
+    );
+    providePermissions(app, evaluator);
+    // Voor de route-middleware (US-Z0503): de evaluator op de Nuxt-app.
+    nuxtApp.provide('authzEvaluator', evaluator);
+
+    // Hydrateer de effectieve permissies. Anoniem/onvoldoende => stil deny-by-default (geen leak).
+    try {
+      await permissions.reload();
+    } catch {
+      // Geen (geldige) sessie: de claims blijven leeg; de evaluator weigert alles. Geen fout lekken.
+    }
+  });
+
+  // 4. Cross-cutting providers voor de surface-pagina's.
+  const i18n = await createI18n({
+    loader: staticCatalogLoader({ nl, en }),
+    supported: ['nl', 'en'],
+    defaultLocale: 'nl',
+    initialLocale: 'nl',
+  });
+  provideI18n(app, i18n);
+
+  const notifications = createNotifications({
+    clock: notifyClock(),
+    scheduler: notifyScheduler(),
+  });
+  provideNotifications(app, notifications);
+
+  provideNavigate(app, (to) => {
+    navigateTo(to);
+  });
+});

package/frontend/templates/runtime.ts

@@ -0,0 +1,60 @@
+/**
+ * Kleine, test-veilige runtime-helpers voor de authorization-surface-pagina's. Géén mechanisme —
+ * puur glue die de pagina's los-koppelt van het host-framework (Nuxt) zodat ze óók bloot in vitest
+ * renderen. Alle helpers zijn per-instance / injectie-gebaseerd: geen module-globale mutable state.
+ *
+ * - `useTranslate()` — leest de i18n-kit-instance als die geprovide is, valt anders veilig terug op
+ *   de sleutel zelf (zodat een pagina zonder i18n-provider tóch rendert; tests zien de sleutel).
+ * - `useNavigate()` / `provideNavigate()` — injecteerbare navigatie; de Nuxt-plugin wired hier
+ *   `navigateTo`; zonder provider is het een no-op (tests hoeven geen router).
+ * - `readQueryParam()` — leest een query-parameter (bv. `id`, `subject`) uit `window.location`,
+ *   test-veilig (happy-dom) en client-safe.
+ * - `useOptionalToasts()` — leest de notifications-toast-store als die geprovide is, anders `undefined`.
+ */
+import { inject, type App, type InjectionKey } from 'vue';
+import { I18N_KEY } from '@seifer-webapp-factory/kits/frontend/i18n/vue';
+import { TOAST_STORE_KEY } from '@seifer-webapp-factory/kits/frontend/notifications/vue';
+import type { UseToasts } from '@seifer-webapp-factory/kits/frontend/notifications/vue';
+
+/** Vertaal-functie: sleutel (+ optionele interpolatie-params) → gelokaliseerde tekst. */
+export type TranslateFn = (key: string, params?: Readonly<Record<string, unknown>>) => string;
+
+/**
+ * Levert een vertaal-functie. Met geprovide i18n-kit: echte vertaling. Zonder: identiteit (de
+ * sleutel zelf), zodat een surface-pagina ook zonder i18n-provider rendert.
+ */
+export function useTranslate(): TranslateFn {
+  const i18n = inject(I18N_KEY, undefined);
+  return (key, params) => (i18n !== undefined ? i18n.t(key, params) : key);
+}
+
+/** Navigatie-functie: stuurt de gebruiker naar een pad (bv. naar de role-editor). */
+export type NavigateFn = (to: string) => void;
+
+/** Injectie-sleutel voor de navigator. Module-constante (geen mutable state). */
+export const AUTHZ_NAVIGATE_KEY: InjectionKey<NavigateFn> = Symbol('authz.navigate');
+
+/** Registreer de navigator op een app-instance (de Nuxt-plugin wired hier `navigateTo`). */
+export function provideNavigate(app: App, navigate: NavigateFn): void {
+  app.provide(AUTHZ_NAVIGATE_KEY, navigate);
+}
+
+/** Haal de navigator op binnen setup(). Zonder provider: een veilige no-op. */
+export function useNavigate(): NavigateFn {
+  return inject(AUTHZ_NAVIGATE_KEY, () => {});
+}
+
+/**
+ * Lees een query-parameter uit de huidige URL. Test-veilig (happy-dom levert `window.location`) en
+ * client-safe. Zonder `window` (SSR): lege string.
+ */
+export function readQueryParam(name: string): string {
+  if (typeof window === 'undefined' || window.location == null) return '';
+  return new URLSearchParams(window.location.search).get(name) ?? '';
+}
+
+/** Haal de (optionele) toast-store op; `undefined` als notifications niet geprovide is. */
+export function useOptionalToasts(): UseToasts['success'] | undefined {
+  const store = inject(TOAST_STORE_KEY, undefined);
+  return store?.success;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@seifer-webapp-factory/authorization",
+  "version": "0.1.0",
+  "description": "authorization — tweede capability-module: verticale, pluggable full-stack autorisatie-feature (RBAC + rol-hiërarchie, rol-toewijzing, default-deny-enforcement via een PDP-guard, optionele ReBAC, admin-UI) die de kits samenbindt via één contract. Eerste module met een module→module-afhankelijkheid op authentication.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    "./contract": {
+      "types": "./dist/contract/index.d.ts",
+      "import": "./dist/contract/index.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/src/index.d.ts",
+      "import": "./dist/backend/src/index.js"
+    },
+    "./frontend": {
+      "types": "./dist/frontend/src/index.d.ts",
+      "import": "./dist/frontend/src/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js"
+    },
+    "./scaffolder": {
+      "types": "./dist/scaffolder/index.d.ts",
+      "import": "./dist/scaffolder/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:backend": "tsc -p tsconfig.backend.json",
+    "test": "vitest run",
+    "test:e2e": "vitest run -c vitest.e2e.config.ts"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0",
+    "zod": "^3.23.0",
+    "@seifer-webapp-factory/kits": "^0.1.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.4.22",
+    "@nestjs/core": "^10.4.22",
+    "@nestjs/platform-express": "^10.4.22",
+    "@nestjs/testing": "^10.4.22",
+    "@playwright/test": "^1.50.0",
+    "@types/pg": "^8.20.0",
+    "@types/supertest": "^6.0.0",
+    "@vitejs/plugin-vue": "^5.2.0",
+    "@vue/test-utils": "^2.4.0",
+    "express": "^4.21.0",
+    "happy-dom": "^15.0.0",
+    "pg": "^8.22.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "supertest": "^7.0.0",
+    "testcontainers": "^10.28.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.7.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.0",
+    "vue": "^3.4.0",
+    "vue-router": "^4.4.0",
+    "zod": "^3.24.0",
+    "@seifer-webapp-factory/kits": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "backend/templates",
+    "frontend/templates",
+    "README.md"
+  ]
+}