khal-os 1.260324.2

package/src/lib/auth/roles.ts

@@ -0,0 +1,50 @@
+/**
+ * Role hierarchy and normalization for Genie OS RBAC.
+ *
+ * Forward-compatible role slugs for Phase 1 (platform scope).
+ * WorkOS auto-prefixes org roles with `org-` in Phase 2,
+ * so platform roles use `platform-` prefix to avoid collisions.
+ */
+
+/** Canonical role hierarchy from least to most privileged. */
+export const ROLE_HIERARCHY = ['member', 'platform-dev', 'platform-admin', 'platform-owner'] as const;
+export type Role = (typeof ROLE_HIERARCHY)[number];
+
+/**
+ * Map legacy / shorthand role slugs to canonical platform role slugs.
+ *
+ * Used during migration (admin → platform-admin) and for convenience
+ * (dev → platform-dev). WorkOS may return legacy slugs during the
+ * transition period.
+ */
+const ROLE_ALIASES: Record<string, Role> = {
+	// Legacy slugs (pre-Phase 1)
+	admin: 'platform-admin',
+	developer: 'platform-dev',
+	owner: 'platform-owner',
+	viewer: 'member',
+	user: 'member',
+	// Shorthand
+	dev: 'platform-dev',
+};
+
+/**
+ * Normalize a role string to a canonical platform role.
+ *
+ * Handles:
+ * - Canonical slugs (returned as-is)
+ * - Legacy slugs (mapped via ROLE_ALIASES)
+ * - Unknown strings (defaults to 'member')
+ */
+export function normalizeRole(role: string | undefined | null): Role {
+	if (!role) return 'member';
+	if (ROLE_HIERARCHY.includes(role as Role)) return role as Role;
+	return ROLE_ALIASES[role] ?? 'member';
+}
+
+/**
+ * Check if a role meets or exceeds the minimum required role level.
+ */
+export function hasMinRole(userRole: Role, minRole: Role): boolean {
+	return ROLE_HIERARCHY.indexOf(userRole) >= ROLE_HIERARCHY.indexOf(minRole);
+}

package/src/lib/auth/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Auth abstraction layer types.
+ *
+ * These types decouple the application from any specific auth provider (WorkOS, BoxyHQ, etc.).
+ * All app code should depend on these interfaces, never on vendor types directly.
+ */
+
+export interface Session {
+	userId: string;
+	orgId: string;
+	role: string;
+	permissions: string[];
+}
+
+export interface User {
+	id: string;
+	email: string;
+	firstName?: string;
+	lastName?: string;
+	avatarUrl?: string;
+}
+
+export interface Permissions {
+	apps: string[];
+	manageMembers: boolean;
+}
+
+export interface AuthProvider {
+	verifySession(cookie: string): Promise<Session | null>;
+	getUser(userId: string): Promise<User>;
+	getOrgPermissions(orgId: string, userId: string): Promise<Permissions>;
+}

package/src/lib/auth/use-auth.ts

@@ -0,0 +1,53 @@
+'use client';
+
+import { useAuth } from '@workos-inc/authkit-nextjs/components';
+import { DEFAULT_ROLE_PERMISSIONS } from '@/components/apps/app-manifest';
+import { normalizeRole } from '@/lib/auth/roles';
+
+export interface KhalAuth {
+	userId: string;
+	orgId: string;
+	role: string;
+	permissions: string[];
+	loading: boolean;
+}
+
+/**
+ * Client-side hook that provides Khal auth state derived from the
+ * WorkOS AuthKit session. Returns null when not authenticated.
+ *
+ * Role is normalized to a canonical platform slug via normalizeRole().
+ * When no role is present, defaults to 'member' (least privilege).
+ *
+ * Permissions are derived from the normalized role using DEFAULT_ROLE_PERMISSIONS.
+ * WorkOS permissions (e.g., "widgets:users-table:manage") are org-level and don't
+ * map to app IDs — role-based defaults provide the correct app-level permissions.
+ */
+export function useKhalAuth(): KhalAuth | null {
+	const { user, role, loading } = useAuth();
+
+	if (loading) {
+		return { userId: '', orgId: '', role: '', permissions: [], loading: true };
+	}
+
+	if (!user) {
+		return null;
+	}
+
+	const effectiveRole = normalizeRole(role);
+	const effectivePermissions = DEFAULT_ROLE_PERMISSIONS[effectiveRole] ?? [];
+
+	const instanceId = process.env.NEXT_PUBLIC_KHAL_INSTANCE_ID;
+	if (!instanceId) {
+		// biome-ignore lint/suspicious/noConsole: startup diagnostic for missing env var
+		console.error('[auth] NEXT_PUBLIC_KHAL_INSTANCE_ID is not set — NATS subjects will not match server');
+	}
+
+	return {
+		userId: user.id,
+		orgId: instanceId || 'default',
+		role: effectiveRole,
+		permissions: effectivePermissions,
+		loading: false,
+	};
+}

package/src/lib/auth/webhook-handler.ts

@@ -0,0 +1,87 @@
+/**
+ * WorkOS webhook event processing + NATS broadcast.
+ *
+ * Parses webhook payloads by event type and publishes role/membership
+ * changes to NATS subjects so connected WS clients can react in real-time.
+ *
+ * Session invalidation approach:
+ * - AuthKit manages sessions via encrypted cookies — no server-side session store.
+ * - On membership.deleted: broadcast via NATS; client-side listener forces logout.
+ * - On membership.updated (role change): broadcast via NATS; client-side listener
+ *   refreshes role from server.
+ * - Sessions expire naturally per WorkOS session config; webhook provides faster feedback.
+ */
+
+import { getNatsConnection } from '@/lib/nats';
+
+/** NATS subjects for auth events. */
+export const AUTH_SUBJECTS = {
+	roleChanged: 'os.auth.role-changed',
+	membershipRevoked: 'os.auth.membership-revoked',
+} as const;
+
+export interface RoleChangedPayload {
+	userId: string;
+	newRole: string;
+	orgId: string;
+	membershipId: string;
+	timestamp: string;
+}
+
+export interface MembershipRevokedPayload {
+	userId: string;
+	orgId: string;
+	membershipId: string;
+	timestamp: string;
+}
+
+/**
+ * Handle organization_membership.updated — extract new role and broadcast.
+ */
+export async function handleMembershipUpdated(data: {
+	userId: string;
+	organizationId: string;
+	id: string;
+	role: { slug: string };
+}): Promise<void> {
+	const payload: RoleChangedPayload = {
+		userId: data.userId,
+		newRole: data.role.slug,
+		orgId: data.organizationId,
+		membershipId: data.id,
+		timestamp: new Date().toISOString(),
+	};
+
+	console.log('[webhook] membership updated — broadcasting role change:', payload);
+
+	const nc = await getNatsConnection();
+	nc.publish(AUTH_SUBJECTS.roleChanged, JSON.stringify(payload));
+}
+
+/**
+ * Handle organization_membership.deleted — broadcast membership revocation.
+ */
+export async function handleMembershipDeleted(data: {
+	userId: string;
+	organizationId: string;
+	id: string;
+}): Promise<void> {
+	const payload: MembershipRevokedPayload = {
+		userId: data.userId,
+		orgId: data.organizationId,
+		membershipId: data.id,
+		timestamp: new Date().toISOString(),
+	};
+
+	console.log('[webhook] membership deleted — broadcasting revocation:', payload);
+
+	const nc = await getNatsConnection();
+	nc.publish(AUTH_SUBJECTS.membershipRevoked, JSON.stringify(payload));
+}
+
+/**
+ * Handle user.updated — log for now, extensible for future broadcasts.
+ */
+export async function handleUserUpdated(data: { id: string; email: string }): Promise<void> {
+	console.log('[webhook] user updated:', { userId: data.id, email: data.email });
+}

package/src/lib/auth/workos.ts

@@ -0,0 +1,67 @@
+/**
+ * WorkOS implementation of the AuthProvider interface.
+ *
+ * Uses @workos-inc/authkit-nextjs SDK for session verification and
+ * @workos-inc/node (via getWorkOS()) for user/org management.
+ */
+
+import { getWorkOS, withAuth } from '@workos-inc/authkit-nextjs';
+import { normalizeRole } from './roles';
+import type { AuthProvider, Permissions, Session, User } from './types';
+
+/** Default app permissions by role (forward-compatible Phase 1 slugs). */
+const ROLE_DEFAULTS: Record<string, { apps: string[]; manageMembers: boolean }> = {
+	'platform-owner': { apps: ['*'], manageMembers: true },
+	'platform-admin': { apps: ['*'], manageMembers: true },
+	'platform-dev': { apps: ['terminal', 'files', 'settings', 'nats-viewer'], manageMembers: false },
+	member: { apps: ['files'], manageMembers: false },
+};
+
+export class WorkOSAuthProvider implements AuthProvider {
+	async verifySession(_cookie: string): Promise<Session | null> {
+		try {
+			const session = await withAuth();
+			if (!session.user) return null;
+
+			return {
+				userId: session.user.id,
+				orgId: session.organizationId ?? '',
+				role: normalizeRole(session.role),
+				permissions: session.permissions ?? [],
+			};
+		} catch {
+			return null;
+		}
+	}
+
+	async getUser(userId: string): Promise<User> {
+		const workos = getWorkOS();
+		const workosUser = await workos.userManagement.getUser(userId);
+
+		return {
+			id: workosUser.id,
+			email: workosUser.email,
+			firstName: workosUser.firstName ?? undefined,
+			lastName: workosUser.lastName ?? undefined,
+			avatarUrl: workosUser.profilePictureUrl ?? undefined,
+		};
+	}
+
+	async getOrgPermissions(orgId: string, _userId: string): Promise<Permissions> {
+		try {
+			const workos = getWorkOS();
+			const org = await workos.organizations.getOrganization(orgId);
+
+			if (org.metadata) {
+				const perms = JSON.parse(org.metadata.permissions ?? '{}') as Partial<Permissions>;
+				if (perms.apps) {
+					return { apps: perms.apps, manageMembers: perms.manageMembers ?? false };
+				}
+			}
+		} catch {
+			// Fall through to defaults
+		}
+
+		return ROLE_DEFAULTS['platform-dev'];
+	}
+}

package/src/lib/constants.ts

@@ -0,0 +1 @@
+export const TASKBAR_HEIGHT = 44;

package/src/lib/desktop/dedup.ts

@@ -0,0 +1,57 @@
+const KEY_PREFIX = 'khal:cmd:';
+const TTL_MS = 10_000;
+
+let _tabId: string;
+function tabId() {
+	if (!_tabId) _tabId = Math.random().toString(36).slice(2);
+	return _tabId;
+}
+
+/** djb2 hash — fast, deterministic, good distribution */
+function djb2(str: string): string {
+	let hash = 5381;
+	for (let i = 0; i < str.length; i++) {
+		hash = (hash * 33) ^ str.charCodeAt(i);
+	}
+	return (hash >>> 0).toString(36);
+}
+
+/** Derive a stable cmdId from subject + payload. All tabs compute the same value. */
+export function deriveCommandId(subject: string, payload: string): string {
+	const bucket = Math.floor(Date.now() / 5000); // 5s window
+	return djb2(subject + payload + bucket);
+}
+
+/**
+ * Try to claim a command via localStorage. Returns true if this tab should process it.
+ *
+ * Uses per-cmdId keys with write-then-verify (optimistic lock).
+ * Each tab writes its unique tabId, then reads back to confirm it won.
+ * This eliminates the TOCTOU race of the old JSON-blob approach.
+ */
+export function claimCommand(cmdId: string): boolean {
+	try {
+		const key = KEY_PREFIX + cmdId;
+
+		// Fast path: already claimed by another tab
+		if (localStorage.getItem(key) !== null) return false;
+
+		// Write our claim
+		const id = tabId();
+		localStorage.setItem(key, id);
+
+		// Verify we won the race (last writer wins, but read-back is consistent)
+		if (localStorage.getItem(key) !== id) return false;
+
+		// Schedule cleanup
+		setTimeout(() => {
+			try {
+				localStorage.removeItem(key);
+			} catch {}
+		}, TTL_MS);
+		return true;
+	} catch {
+		// localStorage unavailable (SSR, private mode quota) — allow execution
+		return true;
+	}
+}

package/src/lib/desktop/schema.ts

@@ -0,0 +1,55 @@
+import { type Static, Type } from '@sinclair/typebox';
+
+// ── Commands (inbound — agents publish, browser executes) ──
+
+export const DesktopCmdOpen = Type.Object({
+	appId: Type.String(),
+	title: Type.Optional(Type.String()),
+	meta: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+	width: Type.Optional(Type.Number()),
+	height: Type.Optional(Type.Number()),
+});
+export type DesktopCmdOpen = Static<typeof DesktopCmdOpen>;
+
+export const DesktopCmdWindow = Type.Object({
+	windowId: Type.String(),
+});
+export type DesktopCmdWindow = Static<typeof DesktopCmdWindow>;
+
+export const DesktopCmdNotify = Type.Object({
+	summary: Type.String(),
+	body: Type.Optional(Type.String()),
+	appName: Type.Optional(Type.String()),
+	urgency: Type.Optional(Type.Union([Type.Literal('low'), Type.Literal('normal'), Type.Literal('critical')])),
+});
+export type DesktopCmdNotify = Static<typeof DesktopCmdNotify>;
+
+// ── Events (outbound — browser publishes, agents observe) ──
+
+export const DesktopWindowEvent = Type.Object({
+	windowId: Type.String(),
+	appId: Type.String(),
+	title: Type.String(),
+	width: Type.Optional(Type.Number()),
+	height: Type.Optional(Type.Number()),
+	meta: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+});
+export type DesktopWindowEvent = Static<typeof DesktopWindowEvent>;
+
+export const DesktopWindowStateEntry = Type.Object({
+	id: Type.String(),
+	appId: Type.String(),
+	title: Type.String(),
+	minimized: Type.Boolean(),
+	maximized: Type.Boolean(),
+	focused: Type.Boolean(),
+	position: Type.Optional(Type.Object({ x: Type.Number(), y: Type.Number() })),
+	size: Type.Optional(Type.Object({ width: Type.Number(), height: Type.Number() })),
+	zIndex: Type.Optional(Type.Number()),
+	meta: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+});
+
+export const DesktopEventState = Type.Object({
+	windows: Type.Array(DesktopWindowStateEntry),
+});
+export type DesktopEventState = Static<typeof DesktopEventState>;

package/src/lib/files/filename-validation.ts

@@ -0,0 +1,41 @@
+/**
+ * Isomorphic filename validation — no Node.js dependencies.
+ * Safe to import from both client (React) and server (API routes / services).
+ */
+
+const FORBIDDEN_CHARS = /[/\\\0]/;
+const TRAVERSAL_SEGMENTS = /(?:^|\/)\.\.(?:\/|$)/;
+const RESERVED_NAMES = /^\.+$/;
+
+/**
+ * Validate a filename (not a path — just the basename).
+ * Returns an error message string if invalid, or `null` if valid.
+ */
+export function validateFilename(name: string): string | null {
+	const trimmed = name.trim();
+	if (trimmed.length === 0) return 'Name cannot be empty';
+	if (trimmed.length > 255) return 'Name is too long (max 255 characters)';
+	if (FORBIDDEN_CHARS.test(trimmed)) return 'Name contains forbidden characters (/ \\ or null)';
+	if (TRAVERSAL_SEGMENTS.test(trimmed)) return 'Name cannot contain path traversal (..)';
+	if (RESERVED_NAMES.test(trimmed)) return 'Name cannot be only dots';
+	return null;
+}
+
+/**
+ * Sanitize a filename by stripping dangerous characters.
+ * Throws if the result is empty after sanitization.
+ */
+export function sanitizeFilename(name: string): string {
+	// Strip null bytes, slashes, backslashes, and path traversal sequences
+	let clean = name
+		.replace(/\0/g, '')
+		.replace(/[/\\]/g, '')
+		.replace(/\.{2,}/g, '.')
+		.trim();
+	// Collapse leading dots to a single dot
+	clean = clean.replace(/^\.+/, '.');
+	if (clean.length === 0) {
+		throw new Error('Filename is empty after sanitization');
+	}
+	return clean;
+}

package/src/lib/files/safe-path.ts

@@ -0,0 +1,49 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export { sanitizeFilename, validateFilename } from './filename-validation';
+
+/** Max single-file upload size: 100 MB */
+export const MAX_UPLOAD_SIZE = 100 * 1024 * 1024;
+
+/** Max entries in a single zip download */
+export const MAX_ZIP_ENTRIES = 100;
+
+export function getFilesRoot(): string {
+	return process.env.KHAL_FILES_ROOT || join(homedir(), 'khal-files');
+}
+
+/**
+ * Resolve a user-provided path safely within the root directory.
+ * Rejects path traversal attempts and symlink escapes.
+ */
+export function resolveSafePath(root: string, userPath: string): string {
+	const resolved = resolve(root, userPath.replace(/^\/+/, ''));
+	if (resolved !== root && !resolved.startsWith(`${root}/`)) {
+		throw new Error('Path traversal detected');
+	}
+	// Symlink escape check: if the target exists, ensure its real path is within root
+	if (existsSync(resolved)) {
+		const real = realpathSync(resolved);
+		if (real !== root && !real.startsWith(`${root}/`)) {
+			throw new Error('Symlink escape detected');
+		}
+	}
+	return resolved;
+}
+
+/**
+ * Encode a filename for use in Content-Disposition headers (RFC 5987).
+ * Uses percent-encoding for non-ASCII and special characters.
+ */
+export function escapeContentDisposition(filename: string): string {
+	// ASCII fallback: replace non-ASCII with underscores
+	const asciiFallback = filename.replace(/[^\x20-\x7E]/g, '_').replace(/"/g, '\\"');
+	// RFC 5987 encoded value
+	const encoded = encodeURIComponent(filename).replace(
+		/['()]/g,
+		(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+	);
+	return `attachment; filename="${asciiFallback}"; filename*=UTF-8''${encoded}`;
+}