@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/server/middleware/permission-checker.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Permission checking middleware for vibeskit
+ *
+ * Uses the enhanced RBAC system for granular permission checking
+ * with caching and ownership validation.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+import type { RequestEvent } from '@sveltejs/kit';
+import type { AuthConfig } from '../../types';
+import { type VibesKitRuntimePort, type VibesKitUser } from '../locals.js';
+/** The parts of a request the checker reads; every `RequestEvent` is one, whatever its route. */
+type PermissionEvent = Pick<RequestEvent, 'locals' | 'request' | 'url'> & {
+    params?: Partial<Record<string, string>>;
+};
+/**
+ * Permission error with detailed context
+ */
+export declare class PermissionError extends CapabilityError {
+    requiredPermissions?: string[] | undefined;
+    userPermissions?: string[] | undefined;
+    /** The response's `error` string (e.g. `INSUFFICIENT_PERMISSIONS`); `.code` is the taxonomy code. */
+    readonly legacyCode: string;
+    constructor(message: string, legacyCode?: string, requiredPermissions?: string[] | undefined, userPermissions?: string[] | undefined);
+    toResponse(): Response;
+}
+/**
+ * Authentication error
+ */
+export declare class AuthenticationError extends CapabilityError {
+    /** The response's `error` string; `.code` is the taxonomy code. */
+    readonly legacyCode = "AUTHENTICATION_REQUIRED";
+    constructor(message?: string);
+    toResponse(): Response;
+}
+/**
+ * Permission checker for vibeskit endpoints
+ */
+export declare class VibesPermissionChecker {
+    /**
+     * Check if user has required permissions
+     */
+    checkPermissions(event: PermissionEvent, config: AuthConfig): Promise<{
+        allowed: boolean;
+        user?: VibesKitUser;
+        reason?: string;
+        requiresOwnershipCheck?: boolean;
+    }>;
+    /**
+     * Check if API key scopes cover the required permissions
+     */
+    private checkApiKeyScopes;
+    /**
+     * Check user permissions using RBAC
+     */
+    private checkUserPermissions;
+    /**
+     * Check resource ownership
+     */
+    private checkOwnership;
+    /**
+     * Invalidate user permission caches
+     */
+    invalidateUserPermissions(runtime: VibesKitRuntimePort, userId: string, projectId?: string | null): Promise<void>;
+}
+/**
+ * Global permission checker instance
+ */
+export declare const globalPermissionChecker: VibesPermissionChecker;
+/**
+ * Apply permission checking middleware
+ */
+export declare function applyPermissionCheck(event: PermissionEvent, config: AuthConfig): Promise<{
+    user?: VibesKitUser;
+    requiresOwnershipCheck?: boolean;
+}>;
+/**
+ * Permission utilities
+ */
+export declare const permissionUtils: {
+    /**
+     * Check if user has specific permissions
+     */
+    hasPermissions(runtime: VibesKitRuntimePort, userId: string, permissions: string[], projectId?: string | null, requireAll?: boolean): Promise<boolean>;
+    /**
+     * Check if user is a superuser (platform admin)
+     */
+    isSuperuser(runtime: VibesKitRuntimePort, userId: string): Promise<boolean>;
+    /**
+     * Check resource ownership
+     */
+    checkOwnership(runtime: VibesKitRuntimePort, userId: string, resourceType: string, resourceId: string, projectId?: string | null): Promise<boolean>;
+    /**
+     * Invalidate user permission caches
+     */
+    invalidateUserPermissions(runtime: VibesKitRuntimePort, userId: string, projectId?: string | null): Promise<void>;
+};
+/**
+ * Permission middleware helpers
+ */
+export declare const permissionMiddleware: {
+    /**
+     * Create auth config for common patterns
+     */
+    requireAuth: () => AuthConfig;
+    requirePermissions: (permissions: string[]) => AuthConfig;
+    requireOwnership: (resourceType: string, paramName: string) => AuthConfig;
+    public: () => AuthConfig;
+    /**
+     * Combine multiple auth requirements
+     */
+    combineAuth: (...configs: AuthConfig[]) => AuthConfig;
+};
+export {};

package/dist/lib/server/middleware/permission-checker.js

@@ -0,0 +1,534 @@
+/**
+ * Permission checking middleware for vibeskit
+ *
+ * Uses the enhanced RBAC system for granular permission checking
+ * with caching and ownership validation.
+ */
+import * as z from 'zod/v4';
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { settle } from '../../attempt.js';
+import { getVibesKit, hasVibesKit } from '../../instance';
+import { kitLogger } from '../../kit-logger';
+import { asVibesKitLocals, requireKitRuntime } from '../locals.js';
+const moduleLogger = kitLogger('vibeskit-permission-checker');
+/**
+ * The session fields the checker reads: whether it is an API-key session and
+ * the scopes that key carries. `scopes` is read as published and validated
+ * before it can grant (a malformed list refuses rather than widening access).
+ */
+const SessionSchema = z.looseObject({
+    type: z.string().optional(),
+    metadata: z.looseObject({ scopes: z.unknown().optional() }).nullish()
+});
+const ScopesSchema = z.array(z.string());
+const HeldRolesSchema = z.array(z.looseObject({ name: z.string() }));
+function getPermissionDependencies() {
+    const kit = hasVibesKit() ? getVibesKit() : null;
+    return {
+        auth: kit?.config.services?.auth,
+        logger: moduleLogger
+    };
+}
+/**
+ * Permission error with detailed context
+ */
+export class PermissionError extends CapabilityError {
+    requiredPermissions;
+    userPermissions;
+    /** The response's `error` string (e.g. `INSUFFICIENT_PERMISSIONS`); `.code` is the taxonomy code. */
+    legacyCode;
+    constructor(message, legacyCode = 'INSUFFICIENT_PERMISSIONS', requiredPermissions, userPermissions) {
+        super(message, 'PERMISSION_DENIED', { reason: legacyCode.toLowerCase().replaceAll('_', '-') });
+        this.requiredPermissions = requiredPermissions;
+        this.userPermissions = userPermissions;
+        this.legacyCode = legacyCode;
+        this.name = 'PermissionError';
+    }
+    toResponse() {
+        return new Response(JSON.stringify({
+            error: this.legacyCode,
+            message: this.message,
+            requiredPermissions: this.requiredPermissions,
+            userPermissions: this.userPermissions
+        }), {
+            status: 403,
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+    }
+}
+/**
+ * Authentication error
+ */
+export class AuthenticationError extends CapabilityError {
+    /** The response's `error` string; `.code` is the taxonomy code. */
+    legacyCode = 'AUTHENTICATION_REQUIRED';
+    constructor(message = 'Authentication required') {
+        super(message, 'AUTH_REQUIRED', { reason: 'authentication-required' });
+        this.name = 'AuthenticationError';
+    }
+    toResponse() {
+        return new Response(JSON.stringify({
+            error: this.legacyCode,
+            message: this.message
+        }), {
+            status: 401,
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+    }
+}
+/**
+ * Permission checker for vibeskit endpoints
+ */
+export class VibesPermissionChecker {
+    /**
+     * Check if user has required permissions
+     */
+    async checkPermissions(event, config) {
+        // Check authentication requirement (support both 'required' and 'requireAuth' keys)
+        const authRequired = config.required || config.requireAuth;
+        // Handle public endpoints. A config that also requires authentication is not
+        // public: `required` beats `public`, whatever order they were combined in.
+        if (config.public && !authRequired) {
+            return { allowed: true };
+        }
+        const user = asVibesKitLocals(event.locals).user;
+        const rolesRequired = Boolean(config.roles?.length);
+        if (authRequired || config.permissions || config.owns || config.adminOnly || rolesRequired) {
+            if (!user) {
+                return {
+                    allowed: false,
+                    reason: 'Authentication required'
+                };
+            }
+        }
+        // Roles: the signed-in user must hold at least one of the listed roles, as
+        // the permission-fetch handle published them on `locals.roles`. No roles
+        // published (or an unreadable list) means no role is held.
+        if (config.roles?.length) {
+            const held = HeldRolesSchema.safeParse(asVibesKitLocals(event.locals).roles);
+            const heldNames = held.success ? held.data.map((role) => role.name) : [];
+            if (!config.roles.some((required) => heldNames.includes(required))) {
+                return { allowed: false, reason: 'Required role missing' };
+            }
+        }
+        const { auth, logger } = getPermissionDependencies();
+        if (!auth) {
+            // When auth is not required and no specific permissions/owns/adminOnly,
+            // allow access even without an auth service configured.
+            if (!authRequired && !config.permissions?.length && !config.owns && !config.adminOnly) {
+                return { allowed: true, user: user ?? undefined };
+            }
+            if (authRequired && !config.permissions && !config.owns && !config.adminOnly) {
+                return { allowed: true, user: user ?? undefined };
+            }
+            if (config.adminOnly && user?.staff === true && !config.permissions && !config.owns) {
+                return { allowed: true, user: user ?? undefined };
+            }
+            logger?.warn('Auth service not injected in vibeskit config', {
+                path: event.url.pathname,
+                authRequired,
+                hasPermissionsCheck: Boolean(config.permissions?.length),
+                hasOwnershipCheck: Boolean(config.owns),
+                adminOnly: Boolean(config.adminOnly),
+                category: 'permissions'
+            });
+            return {
+                allowed: false,
+                reason: config.adminOnly && user && user.staff !== true
+                    ? 'Admin access required'
+                    : 'Auth service not configured for permission checks'
+            };
+        }
+        if (authRequired || config.permissions || config.owns || config.adminOnly) {
+            const runtime = requireKitRuntime(asVibesKitLocals(event.locals));
+            // Check admin-only access first
+            if (config.adminOnly) {
+                const isSuperuser = user && (user.isSuperuser === true || (await auth.isUserSuperuser(runtime, user.id)));
+                if (!isSuperuser) {
+                    // Staff flag bypass — Vibes operator escape hatch when RBAC is unavailable
+                    const userHasStaffFlag = user?.staff === true;
+                    if (!userHasStaffFlag) {
+                        logger?.warn('Admin-only endpoint access denied', {
+                            userId: user?.id,
+                            path: event.url.pathname,
+                            reason: 'User is not admin',
+                            category: 'permissions'
+                        });
+                        return {
+                            allowed: false,
+                            reason: 'Admin access required'
+                        };
+                    }
+                }
+                logger?.debug('Admin access granted', {
+                    userId: user?.id,
+                    path: event.url.pathname,
+                    viaRBAC: isSuperuser,
+                    viaStaffFlag: user?.staff,
+                    category: 'permissions'
+                });
+            }
+            // Check permissions if specified
+            let requiresOwnershipCheck = false;
+            if (config.permissions && config.permissions.length > 0 && user) {
+                const result = await this.checkUserPermissions(user.id, [...config.permissions], event);
+                if (!result.allowed) {
+                    return result;
+                }
+                requiresOwnershipCheck = result.requiresOwnershipCheck || false;
+            }
+            // Check ownership if specified
+            if (config.owns && user) {
+                const ownershipResult = await this.checkOwnership(user.id, config.owns, event);
+                if (!ownershipResult.allowed) {
+                    return ownershipResult;
+                }
+            }
+            return { allowed: true, user: user ?? undefined, requiresOwnershipCheck };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Check if API key scopes cover the required permissions
+     */
+    checkApiKeyScopes(scopes, requiredPermissions) {
+        // Convert required permissions to scope format (resource:action)
+        // Required permissions may have :own suffix which we strip for scope matching
+        const requiredScopes = requiredPermissions.map((perm) => {
+            // Remove :own suffix if present
+            return perm.replace(/:own$/, '');
+        });
+        // Check if all required scopes are covered by the API key scopes
+        return requiredScopes.every((required) => {
+            // Exact match
+            if (scopes.includes(required))
+                return true;
+            // Check for wildcard scopes (e.g., 'knowledge:*' covers 'knowledge:read')
+            const [resource, _action] = required.split(':');
+            if (scopes.includes(`${resource}:*`))
+                return true;
+            // Check for global wildcard
+            if (scopes.includes('*') || scopes.includes('*:*'))
+                return true;
+            return false;
+        });
+    }
+    /**
+     * Check user permissions using RBAC
+     */
+    async checkUserPermissions(userId, requiredPermissions, event) {
+        const { auth, logger } = getPermissionDependencies();
+        if (!auth)
+            return {
+                allowed: false,
+                reason: 'Auth service not configured for permission checks'
+            };
+        const runtime = requireKitRuntime(asVibesKitLocals(event.locals));
+        const decision = await settle(async () => {
+            const params = event.params ?? {};
+            const _klocals = asVibesKitLocals(event.locals);
+            const projectId = _klocals.activeProjectId || params.projectId || null;
+            const session = SessionSchema.safeParse(_klocals.session).data ?? null;
+            // Check if user is admin (has wildcard permissions)
+            // Wrap in try/catch to prevent cache/Redis errors from failing the entire permission check
+            let isSuperuser = _klocals.user?.isSuperuser === true;
+            if (!isSuperuser) {
+                const superuserCheck = await settle(() => auth.isUserSuperuser(runtime, userId));
+                if (superuserCheck.ok) {
+                    isSuperuser = superuserCheck.value;
+                }
+                else {
+                    logger?.warn('isUserSuperuser check failed, assuming non-superuser', {
+                        userId,
+                        error: superuserCheck.error,
+                        category: 'permissions'
+                    });
+                }
+            }
+            // For API key sessions, the key's scopes only NARROW what the owner allows:
+            // a key that does not cover the permission is refused for every principal
+            // (superusers included), and a covering key still needs the owner's verdict
+            // below. Scopes never grant on their own.
+            if (session?.type === 'apiKey' && session.metadata?.scopes) {
+                const declaredScopes = ScopesSchema.safeParse(session.metadata.scopes);
+                if (!declaredScopes.success) {
+                    // A key whose scopes cannot be read is not unrestricted: refuse.
+                    logger?.warn('API key scopes are malformed', {
+                        userId,
+                        path: event.url.pathname,
+                        category: 'permissions'
+                    });
+                    return { allowed: false, reason: 'API key scopes are malformed' };
+                }
+                const scopes = declaredScopes.data;
+                const scopesAllowed = this.checkApiKeyScopes(scopes, requiredPermissions);
+                if (!scopesAllowed) {
+                    // API key doesn't have required scopes
+                    logger?.warn('API key lacks required scopes', {
+                        userId,
+                        requiredPermissions: requiredPermissions.join(', '),
+                        scopes: scopes.join(', '),
+                        path: event.url.pathname,
+                        category: 'permissions'
+                    });
+                    return {
+                        allowed: false,
+                        reason: `Insufficient permissions. Required: ${requiredPermissions.join(', ')}. API key scopes: ${scopes.join(', ')}`
+                    };
+                }
+            }
+            // The owner's verdict: an auth-declared superuser is allowed.
+            if (isSuperuser) {
+                logger?.debug('Permission granted via superuser verdict', {
+                    userId,
+                    requiredPermissions: requiredPermissions.join(', '),
+                    path: event.url.pathname,
+                    category: 'permissions'
+                });
+                return { allowed: true };
+            }
+            // Parse permissions for the interface
+            const permissionObjects = requiredPermissions.map((perm) => {
+                const parts = perm.split(':');
+                const resource = parts[0];
+                // Remove :own suffix if present for the base permission check
+                const action = parts.slice(1).join(':').replace(/:own$/, '');
+                return { resource, action };
+            });
+            // Check if we have the base permissions via DB/RBAC
+            const allowed = await auth.hasPermissions(runtime, userId, permissionObjects, projectId);
+            if (!allowed) {
+                logger?.warn('User lacks required permissions', {
+                    userId,
+                    requiredPermissions: requiredPermissions.join(', '),
+                    projectId,
+                    path: event.url.pathname,
+                    category: 'permissions'
+                });
+                return {
+                    allowed: false,
+                    reason: `Insufficient permissions. Required: ${requiredPermissions.join(', ')}`
+                };
+            }
+            // Check if any permission required ownership (:own suffix)
+            // We'll flag this for the caller to handle or check explicitly
+            const requiresOwnershipCheck = requiredPermissions.some((p) => p.endsWith(':own'));
+            logger?.debug('Permission check completed', {
+                userId,
+                requiredPermissions: requiredPermissions.join(', '),
+                projectId,
+                allowed: true,
+                requiresOwnershipCheck,
+                category: 'permissions'
+            });
+            return {
+                allowed: true,
+                requiresOwnershipCheck
+            };
+        });
+        if (decision.ok)
+            return decision.value;
+        logger?.error('Permission check error', decision.error, {
+            userId,
+            requiredPermissions: requiredPermissions.join(', '),
+            category: 'permissions'
+        });
+        return {
+            allowed: false,
+            reason: 'Permission check failed due to error'
+        };
+    }
+    /**
+     * Check resource ownership
+     */
+    async checkOwnership(userId, ownsConfig, event) {
+        const { auth, logger } = getPermissionDependencies();
+        if (!auth)
+            return {
+                allowed: false,
+                reason: 'Auth service not configured for permission checks'
+            };
+        const runtime = requireKitRuntime(asVibesKitLocals(event.locals));
+        const params = event.params ?? {};
+        const resourceId = params[ownsConfig.paramName];
+        if (!resourceId) {
+            return {
+                allowed: false,
+                reason: `Resource ID parameter '${ownsConfig.paramName}' not found`
+            };
+        }
+        const projectId = asVibesKitLocals(event.locals).activeProjectId || params.projectId || null;
+        const ownership = await settle(() => auth.checkOwnership(runtime, userId, ownsConfig.resourceType, resourceId, projectId));
+        if (!ownership.ok) {
+            logger?.error('Ownership check error', ownership.error, {
+                userId,
+                ownsConfig,
+                category: 'permissions'
+            });
+            return {
+                allowed: false,
+                reason: 'Ownership check failed due to error'
+            };
+        }
+        const isOwner = ownership.value;
+        {
+            if (!isOwner) {
+                logger?.warn('Resource ownership check failed', {
+                    userId,
+                    resourceType: ownsConfig.resourceType,
+                    resourceId,
+                    projectId,
+                    category: 'permissions'
+                });
+                return {
+                    allowed: false,
+                    reason: `User does not own ${ownsConfig.resourceType} with ID ${resourceId}`
+                };
+            }
+            logger?.debug('Resource ownership confirmed', {
+                userId,
+                resourceType: ownsConfig.resourceType,
+                resourceId,
+                projectId,
+                category: 'permissions'
+            });
+            return { allowed: true };
+        }
+    }
+    /**
+     * Invalidate user permission caches
+     */
+    async invalidateUserPermissions(runtime, userId, projectId) {
+        const { auth } = getPermissionDependencies();
+        await auth?.invalidateUserPermissions?.(runtime, userId, projectId);
+    }
+}
+/**
+ * Global permission checker instance
+ */
+export const globalPermissionChecker = new VibesPermissionChecker();
+/**
+ * Apply permission checking middleware
+ */
+export async function applyPermissionCheck(event, config) {
+    const { logger } = getPermissionDependencies();
+    const result = await globalPermissionChecker.checkPermissions(event, config);
+    if (!result.allowed) {
+        if (result.reason?.includes('Authentication required')) {
+            logger?.warn('Authentication required', {
+                path: event.url.pathname,
+                method: event.request.method,
+                category: 'auth'
+            });
+            throw new AuthenticationError(result.reason);
+        }
+        else {
+            logger?.warn('Permission denied', {
+                path: event.url.pathname,
+                method: event.request.method,
+                reason: result.reason,
+                category: 'permissions'
+            });
+            throw new PermissionError(result.reason || 'Access denied', 'ACCESS_DENIED', config.permissions ? [...config.permissions] : undefined);
+        }
+    }
+    // Store ownership check requirement in locals for handler
+    if (result.requiresOwnershipCheck) {
+        asVibesKitLocals(event.locals).requiresOwnershipCheck = true;
+    }
+    return {
+        user: result.user,
+        requiresOwnershipCheck: result.requiresOwnershipCheck
+    };
+}
+/**
+ * Permission utilities
+ */
+export const permissionUtils = {
+    /**
+     * Check if user has specific permissions
+     */
+    async hasPermissions(runtime, userId, permissions, projectId, requireAll = false) {
+        const { auth } = getPermissionDependencies();
+        if (!auth)
+            return false;
+        const permissionObjects = permissions.map((perm) => {
+            const parts = perm.split(':');
+            return {
+                resource: parts[0],
+                action: parts.slice(1).join(':')
+            };
+        });
+        return await auth.hasPermissions(runtime, userId, permissionObjects, projectId, requireAll);
+    },
+    /**
+     * Check if user is a superuser (platform admin)
+     */
+    async isSuperuser(runtime, userId) {
+        const { auth } = getPermissionDependencies();
+        if (!auth)
+            return false;
+        return await auth.isUserSuperuser(runtime, userId);
+    },
+    /**
+     * Check resource ownership
+     */
+    async checkOwnership(runtime, userId, resourceType, resourceId, projectId) {
+        const { auth } = getPermissionDependencies();
+        if (!auth)
+            return false;
+        return await auth.checkOwnership(runtime, userId, resourceType, resourceId, projectId);
+    },
+    /**
+     * Invalidate user permission caches
+     */
+    invalidateUserPermissions(runtime, userId, projectId) {
+        return globalPermissionChecker.invalidateUserPermissions(runtime, userId, projectId);
+    }
+};
+/**
+ * Permission middleware helpers
+ */
+export const permissionMiddleware = {
+    /**
+     * Create auth config for common patterns
+     */
+    requireAuth: () => ({ required: true }),
+    requirePermissions: (permissions) => ({
+        required: true,
+        permissions
+    }),
+    requireOwnership: (resourceType, paramName) => ({
+        required: true,
+        owns: { resourceType, paramName }
+    }),
+    public: () => ({ public: true }),
+    /**
+     * Combine multiple auth requirements
+     */
+    combineAuth: (...configs) => {
+        const merged = configs.reduce((combined, config) => ({
+            ...combined,
+            ...config,
+            permissions: [...(combined.permissions || []), ...(config.permissions || [])]
+        }), {});
+        // Requirements accumulate whatever the order: a later config cannot relax an
+        // earlier one, and `required` beats `public`.
+        const required = configs.some((config) => config.required === true);
+        const requireAuth = configs.some((config) => config.requireAuth === true);
+        const adminOnly = configs.some((config) => config.adminOnly === true);
+        if (required)
+            merged.required = true;
+        if (requireAuth)
+            merged.requireAuth = true;
+        if (adminOnly)
+            merged.adminOnly = true;
+        if (required || requireAuth || adminOnly)
+            delete merged.public;
+        return merged;
+    }
+};