@lego-box/shell 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lego-box/shell",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Piral microfrontend shell for Lego Box - provides authentication, PocketBase integration, RBAC, and shared UI components",
   "keywords": [
     "piral",
@@ -25,8 +25,7 @@
   "files": [
     "dist/emulator",
     "pilet.ts",
-    "src/types.ts",
-    "src/auth/ability.ts",
+    "src",
     "README.md"
   ],
   "main": "dist/emulator/index.js",

package/src/auth/auth-store.ts

@@ -0,0 +1,33 @@
+import type { AppAbility } from './ability';
+import type { PermissionString } from '../types';
+
+/**
+ * Module-level store for auth/CASL data.
+ * AbilityProvider populates this; plugins and pilets read from it.
+ */
+let abilityRef: AppAbility | null = null;
+let roleNameRef: string | null = null;
+let permissionsRef: PermissionString[] = [];
+
+export function setAuthCaslStore(ability: AppAbility, roleName: string | null, permissions: PermissionString[]) {
+  abilityRef = ability;
+  roleNameRef = roleName;
+  permissionsRef = permissions;
+}
+
+export function getAbility(): AppAbility | null {
+  return abilityRef;
+}
+
+export function getRoleName(): string | null {
+  return roleNameRef;
+}
+
+export function getPermissions(): PermissionString[] {
+  return permissionsRef;
+}
+
+export function can(action: string, subject: string): boolean {
+  if (!abilityRef) return false;
+  return abilityRef.can(action, subject);
+}

package/src/auth/auth.ts

@@ -0,0 +1,176 @@
+import type { PiralPlugin } from 'piral';
+import type PocketBase from 'pocketbase';
+import type { AuthUser, UserType } from '../types';
+import { trackUserLogin } from '../services/telemetry';
+
+/** piral-auth UserInfo shape (id, firstName, lastName, mail, language, permissions, features). */
+interface UserInfo {
+  id: string;
+  firstName: string;
+  lastName: string;
+  mail: string;
+  language: string;
+  permissions: Record<string, unknown>;
+  features: Record<string, boolean>;
+}
+
+function authUserToUserInfo(user: AuthUser, userType: UserType): UserInfo {
+  const parts = user.name.trim().split(/\s+/);
+  const firstName = parts[0] ?? user.name;
+  const lastName = parts.slice(1).join(' ') ?? '';
+  return {
+    id: user.id,
+    firstName,
+    lastName,
+    mail: user.email,
+    language: '',
+    permissions: { userType: userType ?? 'user' },
+    features: userType === 'admin' ? { admin: true } : {},
+  };
+}
+
+function userInfoToAuthUser(info: UserInfo | undefined): AuthUser | undefined {
+  if (!info) return undefined;
+  const name = [info.firstName, info.lastName].filter(Boolean).join(' ').trim() || info.mail;
+  return {
+    id: info.id,
+    email: info.mail,
+    name,
+  };
+}
+
+/** Minimal shape needed to derive UserType (permissions.userType or features.admin). */
+export type UserInfoLike = { permissions?: Record<string, unknown>; features?: Record<string, boolean> };
+
+/** Derives UserType from piral-auth UserInfo (permissions.userType or features.admin). */
+export function getUserTypeFromUserInfo(info: UserInfo | UserInfoLike | undefined): UserType {
+  if (!info) return null;
+  const t = info.permissions?.userType;
+  if (t === 'admin' || t === 'user') return t;
+  return info.features?.admin ? 'admin' : 'user';
+}
+
+/** piral-auth UserInfo for createAuthApi({ user }) initial state. */
+export interface UserInfoForPiralAuth {
+  id: string;
+  firstName: string;
+  lastName: string;
+  mail: string;
+  language: string;
+  permissions: Record<string, unknown>;
+  features: Record<string, boolean>;
+}
+
+/**
+ * Builds initial user for piral-auth from PocketBase authStore (localStorage by default).
+ * Call before createInstance and pass to createAuthApi({ user }) so auth persists on refresh.
+ */
+export function getInitialUserFromPb(
+  pb: PocketBase
+): UserInfoForPiralAuth | undefined {
+  if (typeof document === 'undefined' || !pb.authStore.isValid || !pb.authStore.model) {
+    return undefined;
+  }
+  const model = pb.authStore.model as Record<string, unknown>;
+  const email = String(model.email ?? '');
+  const name = String(model.name ?? model.email ?? email);
+  const id = String(model.id ?? 'admin');
+  // PocketBase: users have collectionId; admins do not (see docs)
+  const isAdmin = !('collectionId' in model && model.collectionId);
+  const userType: UserType = isAdmin ? 'admin' : 'user';
+  const authUser: AuthUser = { id, email, name };
+  return authUserToUserInfo(authUser, userType);
+}
+
+/**
+ * Creates a Piral plugin that adds PocketBase-backed auth: login (user then admin),
+ * logout, isAuthenticated, getUser, getUserId, getUserType. Syncs with piral-auth state via setUser.
+ */
+export function createPocketBaseAuthPlugin(
+  pb: PocketBase
+): PiralPlugin<Record<string, unknown>> {
+  return (context) => {
+    const setUser = (context as unknown as { setUser?: (u: UserInfo | undefined) => void }).setUser;
+
+    // Keep Piral auth state in sync with PocketBase authStore (e.g. restore from localStorage, or clear)
+    if (typeof setUser === 'function' && typeof pb.authStore.onChange === 'function') {
+      pb.authStore.onChange(() => {
+        const next = getInitialUserFromPb(pb);
+        setUser(next as UserInfo | undefined);
+      });
+    }
+
+    return {
+      isAuthenticated() {
+        return pb.authStore.isValid;
+      },
+      getUser(): AuthUser | undefined {
+        const state = context.readState((s: unknown) => (s as { user?: UserInfo }).user);
+        return userInfoToAuthUser(state);
+      },
+      getUserId(): string | null {
+        const user = context.readState((s: unknown) => (s as { user?: UserInfo }).user);
+        return user?.id ?? null;
+      },
+      getUserType(): UserType {
+        const user = context.readState((s: unknown) => (s as { user?: UserInfo }).user);
+        return getUserTypeFromUserInfo(user);
+      },
+      async login(email: string, password: string) {
+        try {
+          const authData = await pb.collection('users').authWithPassword(email, password);
+          const record = authData.record as Record<string, unknown>;
+          
+          // Check if user is active
+          const isActive = record.isActive !== false; // Default to true if not set
+          if (!isActive) {
+            // Clear the auth store since we don't want inactive users to be logged in
+            pb.authStore.clear();
+            
+            // Track failed login due to inactive account
+            await trackUserLogin(pb, {
+              userId: String(record.id),
+              emailAttempted: email,
+              success: false,
+              failureReason: 'Account is deactivated',
+            });
+            
+            throw new Error('Your account has been deactivated. Please contact an administrator.');
+          }
+          
+          const authUser: AuthUser = {
+            id: String(record.id),
+            email: String(record.email ?? email),
+            name: String(record.name ?? record.email ?? email),
+            avatar: record.avatar as string | undefined,
+          };
+          const userInfo = authUserToUserInfo(authUser, 'user');
+          (context as unknown as { setUser?: (u: UserInfo) => void }).setUser?.(userInfo);
+          
+          // Track successful login
+          await trackUserLogin(pb, {
+            userId: authUser.id,
+            emailAttempted: email,
+            success: true,
+          });
+        } catch (userErr) {
+          // Re-throw our deactivation error as-is
+          if (userErr instanceof Error && userErr.message.includes('deactivated')) {
+            throw userErr;
+          }
+          // Track failed login (invalid credentials)
+          await trackUserLogin(pb, {
+            emailAttempted: email,
+            success: false,
+            failureReason: 'Invalid email or password',
+          });
+          throw new Error('Invalid email or password');
+        }
+      },
+      logout() {
+        pb.authStore.clear();
+        (context as unknown as { setUser?: (u: UserInfo | undefined) => void }).setUser?.(undefined as unknown as UserInfo);
+      },
+    };
+  };
+}

package/src/components/ProtectedPage.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { useGlobalStateContext } from 'piral';
+import { AccessDenied, Loading } from '@lego-box/ui-kit';
+import { useCan, useAbilityLoading } from '../context/AbilityContext';
+
+export interface ProtectedPageProps {
+  /** CASL action (e.g. "read") */
+  action: string;
+  /** CASL subject (e.g. "migrations") */
+  subject: string;
+  children: React.ReactNode;
+}
+
+/**
+ * ProtectedPage - Wraps a page and enforces permission. If the user lacks the required
+ * permission, shows a static Access Denied page. Use for route-level protection.
+ */
+export function ProtectedPage({
+  action,
+  subject,
+  children,
+}: ProtectedPageProps) {
+  const can = useCan();
+  const loading = useAbilityLoading();
+  const ctx = useGlobalStateContext();
+  const allowed = can(action, subject);
+
+  const handleGoHome = () => {
+    ctx?.navigation?.replace?.('/');
+  };
+
+  if (loading) {
+    return <Loading message="Checking permissions..." fullPage={true} />;
+  }
+
+  if (!allowed) {
+    return (
+      <AccessDenied
+        title="Access Denied"
+        description="You don't have permission to view this page."
+        onNavigateHome={handleGoHome}
+        homeButtonText="Go Back Home"
+      />
+    );
+  }
+
+  return <>{children}</>;
+}

package/src/config/env.node.ts

@@ -0,0 +1,38 @@
+/**
+ * Environment config for Node scripts (migrations, CLI).
+ * Uses only process.env and require('dotenv') so it works under ts-node (CommonJS).
+ * Same env var names and defaults as env.ts so .env works for both app and migrations.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+require('dotenv').config();
+
+export interface EnvConfig {
+  pocketbaseUrl: string;
+  adminEmail: string;
+  adminPassword: string;
+  appName: string;
+  appIdentifier: string;
+}
+
+export const env: EnvConfig = {
+  pocketbaseUrl:
+    process.env.VITE_POCKETBASE_URL ||
+    process.env.POCKETBASE_URL ||
+    'http://localhost:8090',
+  adminEmail:
+    process.env.POCKETBASE_ADMIN_EMAIL ||
+    process.env.VITE_POCKETBASE_ADMIN_EMAIL ||
+    'superuser@legobox.local',
+  adminPassword:
+    process.env.POCKETBASE_ADMIN_PASSWORD ||
+    process.env.VITE_POCKETBASE_ADMIN_PASSWORD ||
+    'SuperUser123!',
+  appName:
+    process.env.VITE_APP_NAME ||
+    process.env.APP_NAME ||
+    'Lego Box',
+  appIdentifier:
+    process.env.VITE_APP_IDENTIFIER ||
+    process.env.APP_IDENTIFIER ||
+    'lego-box-default',
+};

package/src/config/env.ts

@@ -0,0 +1,103 @@
+/**
+ * Environment configuration for the browser app.
+ * Uses process.env (injected by Webpack DefinePlugin) for build-time env vars.
+ *
+ * Feed URL format for local pilets: `http://localhost:{PORT}/$pilet-api`
+ * Feed URL format for remote feeds: `https://feed.example.com/api/v1/pilet`
+ *
+ * To configure multiple feeds via environment variable, set VITE_FEED_URLS to a JSON array:
+ *   VITE_FEED_URLS=["http://localhost:9000/$pilet-api", "http://localhost:9001/$pilet-api"]
+ */
+
+/**
+ * Environment configuration consumed by the browser app.
+ *
+ * @property pocketbaseUrl - PocketBase instance URL for API requests
+ * @property adminEmail - Admin email for PocketBase authentication
+ * @property adminPassword - Admin password for PocketBase authentication
+ * @property appName - Human-readable application display name
+ * @property appIdentifier - Unique identifier for this app instance
+ * @property feedUrls - Array of feed URLs to aggregate pilets from (local or remote)
+ */
+export interface EnvConfig {
+  pocketbaseUrl: string;
+  adminEmail: string;
+  adminPassword: string;
+  appName: string;
+  appIdentifier: string;
+  feedUrls: string[];
+}
+
+/** Simple URL validation (handles http, https, localhost) */
+function isValidUrl(s: string): boolean {
+  try {
+    const u = new URL(s);
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/** Validates raw env config; throws with message on failure */
+function validateEnvConfig(raw: EnvConfig): EnvConfig {
+  const errors: string[] = [];
+  if (!raw.pocketbaseUrl || typeof raw.pocketbaseUrl !== 'string' || !raw.pocketbaseUrl.trim()) {
+    errors.push('pocketbaseUrl: required non-empty string');
+  }
+  if (!raw.adminEmail || typeof raw.adminEmail !== 'string' || !raw.adminEmail.trim()) {
+    errors.push('adminEmail: required non-empty string');
+  }
+  if (typeof raw.adminPassword !== 'string') {
+    errors.push('adminPassword: required string');
+  }
+  if (!raw.appName || typeof raw.appName !== 'string' || !raw.appName.trim()) {
+    errors.push('appName: required non-empty string');
+  }
+  if (!raw.appIdentifier || typeof raw.appIdentifier !== 'string' || !raw.appIdentifier.trim()) {
+    errors.push('appIdentifier: required non-empty string');
+  }
+  if (!Array.isArray(raw.feedUrls)) {
+    errors.push('feedUrls: required array');
+  } else if (!raw.feedUrls.every((u) => typeof u === 'string' && isValidUrl(u))) {
+    errors.push('feedUrls: all elements must be valid URLs');
+  }
+  if (errors.length > 0) {
+    throw new Error(`Env config validation failed: ${errors.join('; ')}`);
+  }
+  return raw;
+}
+
+/**
+ * Build-time env vars (injected by Webpack DefinePlugin).
+ * MUST use static references only - e.g. process.env.VITE_FEED_URLS, not process.env[name].
+ * Dynamic access leaves process in the bundle and throws "process is not defined" in browser.
+ */
+function parseFeedUrls(): string[] {
+  const viteRaw = process.env.VITE_FEED_URLS;
+  if (viteRaw && typeof viteRaw === 'string') {
+    try {
+      const parsed = JSON.parse(viteRaw) as unknown;
+      if (Array.isArray(parsed) && parsed.every((x) => typeof x === 'string')) {
+        return parsed as string[];
+      }
+    } catch {
+      /* fall through */
+    }
+  }
+  const feedUrl = process.env.FEED_URL;
+  if (feedUrl && typeof feedUrl === 'string' && feedUrl.trim()) {
+    return [feedUrl.trim()];
+  }
+  return ['http://localhost:9000/$pilet-api'];
+}
+
+const rawEnv: EnvConfig = {
+  pocketbaseUrl: process.env.VITE_POCKETBASE_URL || 'http://localhost:8090',
+  adminEmail: process.env.VITE_POCKETBASE_ADMIN_EMAIL || 'superuser@legobox.local',
+  adminPassword: process.env.VITE_POCKETBASE_ADMIN_PASSWORD || 'SuperUser123!',
+  appName: process.env.VITE_APP_NAME || 'Lego Box',
+  appIdentifier: process.env.VITE_APP_IDENTIFIER || 'lego-box-default',
+  feedUrls: parseFeedUrls(),
+};
+
+export const env: EnvConfig = validateEnvConfig(rawEnv);

package/src/context/AbilityContext.tsx

@@ -0,0 +1,213 @@
+import * as React from 'react';
+import type PocketBase from 'pocketbase';
+import {
+  defineAbilityFor,
+  parsePermissionString,
+  type AppAbility,
+} from '../auth/ability';
+import { setAuthCaslStore } from '../auth/auth-store';
+import { usePiralInstance } from './PiralInstanceContext';
+
+interface AbilityContextValue {
+  ability: AppAbility;
+  loading: boolean;
+}
+
+const AbilityContext = React.createContext<AbilityContextValue | null>(null);
+
+/**
+ * AbilityProvider - Provides CASL ability instance throughout the React tree.
+ * Fetches current user and role permissions from PocketBase, builds ability,
+ * and subscribes to auth/role changes to rebuild when needed.
+ */
+export function AbilityProvider({ children }: { children: React.ReactNode }) {
+  const instance = usePiralInstance();
+  const pb = React.useMemo(
+    () => (instance as unknown as { root?: { pocketbase?: PocketBase } })?.root?.pocketbase,
+    [instance]
+  );
+
+  const [ability, setAbility] = React.useState<AppAbility>(() =>
+    defineAbilityFor(null, [])
+  );
+  const [loading, setLoading] = React.useState(true);
+  const unsubRef = React.useRef<{ roles?: () => void; users?: () => void }>({});
+
+  const buildAbility = React.useCallback(async () => {
+    if (!pb) {
+      const empty = defineAbilityFor(null, []);
+      setAbility(empty);
+      setAuthCaslStore(empty, null, []);
+      setLoading(false);
+      return;
+    }
+
+    const model = pb.authStore.model as Record<string, unknown> | null;
+    if (!model) {
+      const empty = defineAbilityFor(null, []);
+      setAbility(empty);
+      setAuthCaslStore(empty, null, []);
+      setLoading(false);
+      return;
+    }
+
+    const isSuperuser = model.is_superuser === true;
+    const user = {
+      id: String(model.id ?? ''),
+      is_superuser: isSuperuser,
+      role: Array.isArray(model.role) ? model.role[0] : model.role,
+    } as { id: string; is_superuser?: boolean; role?: string };
+
+    if (isSuperuser) {
+      const ab = defineAbilityFor(user, []);
+      setAbility(ab);
+      setAuthCaslStore(ab, 'Superuser', ['manage:all']);
+      setLoading(false);
+      return;
+    }
+
+    const roleId =
+      typeof user.role === 'string'
+        ? user.role
+        : Array.isArray(user.role)
+          ? user.role[0]
+          : undefined;
+
+    if (!roleId) {
+      const ab = defineAbilityFor(user, []);
+      setAbility(ab);
+      setAuthCaslStore(ab, null, []);
+      setLoading(false);
+      return;
+    }
+
+    try {
+      const roleRecord = await pb.collection('roles').getOne(roleId, {
+        fields: 'permissions,name',
+        $autoCancel: false,
+      });
+      const permissionValues = Array.isArray(roleRecord.permissions)
+        ? (roleRecord.permissions as string[]).filter(
+            (p): p is string => typeof p === 'string' && p.length > 0
+          )
+        : [];
+
+      const permissionDefs: Array<{ action: string; subject: string }> = [];
+
+      // Split into permission names (e.g. "read:users") vs IDs (PocketBase record IDs)
+      const permissionNames = permissionValues.filter((v) => v.includes(':'));
+      const permissionIds = permissionValues.filter((v) => !v.includes(':'));
+
+      // Permission names: parse directly
+      for (const name of permissionNames) {
+        const parsed = parsePermissionString(name);
+        if (parsed) permissionDefs.push(parsed);
+      }
+
+      // Permission IDs: fetch records and map to action/subject
+      if (permissionIds.length > 0) {
+        const filter =
+          permissionIds.length === 1
+            ? `id = "${permissionIds[0]}"`
+            : `(${permissionIds.map((id) => `id = "${id}"`).join(' || ')})`;
+        const permRecords = await pb.collection('permissions').getFullList({
+          filter,
+          fields: 'action,collection,name',
+          $autoCancel: false,
+        });
+        for (const r of permRecords as Array<{ action?: string; collection?: string; name?: string }>) {
+          const action = r.action ?? parsePermissionString(r.name ?? '')?.action;
+          const subject = r.collection ?? parsePermissionString(r.name ?? '')?.subject;
+          if (action && subject) permissionDefs.push({ action, subject });
+        }
+      }
+
+      const roleName = (roleRecord as { name?: string }).name ?? null;
+      const permissionStrings: string[] = permissionDefs.map((p) => `${p.action}:${p.subject}`);
+      const ab = defineAbilityFor(user, permissionDefs);
+      setAbility(ab);
+      setAuthCaslStore(ab, roleName, permissionStrings);
+    } catch (err) {
+      console.error('[AbilityProvider] Error fetching role:', err);
+      const ab = defineAbilityFor(user, []);
+      setAbility(ab);
+      setAuthCaslStore(ab, null, []);
+    } finally {
+      setLoading(false);
+    }
+  }, [pb]);
+
+  React.useEffect(() => {
+    setLoading(true);
+    buildAbility();
+  }, [buildAbility]);
+
+  React.useEffect(() => {
+    if (!pb) return;
+
+    const onAuthChange = () => {
+      setLoading(true);
+      buildAbility();
+    };
+
+    const unsubscribe = pb.authStore.onChange(onAuthChange);
+
+    const ref = unsubRef.current;
+
+    pb.collection('roles')
+      .subscribe('*', onAuthChange)
+      .then((unsub) => {
+        ref.roles = unsub;
+      })
+      .catch(() => {});
+    pb.collection('users')
+      .subscribe('*', onAuthChange)
+      .then((unsub) => {
+        ref.users = unsub;
+      })
+      .catch(() => {});
+
+    return () => {
+      unsubscribe();
+      ref.roles?.();
+      ref.users?.();
+      ref.roles = undefined;
+      ref.users = undefined;
+    };
+  }, [pb, buildAbility]);
+
+  const value = React.useMemo(() => ({ ability, loading }), [ability, loading]);
+
+  return (
+    <AbilityContext.Provider value={value}>
+      {children}
+    </AbilityContext.Provider>
+  );
+}
+
+/** Returns the current ability instance from context. */
+export function useAbility(): AppAbility {
+  const ctx = React.useContext(AbilityContext);
+  if (!ctx) {
+    throw new Error('useAbility must be used within AbilityProvider');
+  }
+  return ctx.ability;
+}
+
+/** Returns whether the ability is still loading (e.g. fetching permissions). */
+export function useAbilityLoading(): boolean {
+  const ctx = React.useContext(AbilityContext);
+  if (!ctx) {
+    throw new Error('useAbilityLoading must be used within AbilityProvider');
+  }
+  return ctx.loading;
+}
+
+/** Convenience hook: returns (action, subject) => ability.can(action, subject). */
+export function useCan(): (action: string, subject: string) => boolean {
+  const ability = useAbility();
+  return React.useCallback(
+    (action: string, subject: string) => ability.can(action, subject),
+    [ability]
+  );
+}

package/src/context/PiralInstanceContext.tsx

@@ -0,0 +1,17 @@
+import * as React from 'react';
+
+/** Piral instance type (has context and root API). */
+export interface PiralInstanceLike {
+  context: unknown;
+  root: unknown;
+}
+
+const PiralInstanceContext = React.createContext<PiralInstanceLike | null>(
+  null
+);
+
+export const PiralInstanceProvider = PiralInstanceContext.Provider;
+
+export function usePiralInstance(): PiralInstanceLike | null {
+  return React.useContext(PiralInstanceContext);
+}

package/src/hooks/index.ts

@@ -0,0 +1,11 @@
+export { useUsers, useUserCounts } from './useUsers';
+export { useRoles } from './useRoles';
+export { usePermissions } from './usePermissions';
+
+export { useAbility, useCan, useAbilityLoading } from '../context/AbilityContext';
+export { usePermissionGuard, PermissionGuard } from './usePermissionGuard';
+
+export { useAuditLogs } from './useAuditLogs';
+export { useDebounce } from './useDebounce';
+export { useTickets } from './useTickets';
+export { useUserLogins } from './useUserLogins';