create-ekka-desktop-app 0.2.2

package/template/src/ekka/__tests__/demo-backend.test.ts

@@ -0,0 +1,187 @@
+/**
+ * DemoBackend Tests
+ *
+ * Tests for the in-memory demo backend.
+ * Only tests IMPLEMENTED operations.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { DemoBackend } from '../backend/demo';
+import { OPS } from '../constants';
+import { makeRequest } from '../types';
+
+describe('DemoBackend', () => {
+  let backend: DemoBackend;
+
+  beforeEach(() => {
+    backend = new DemoBackend();
+  });
+
+  describe('connection', () => {
+    it('starts disconnected', () => {
+      expect(backend.isConnected()).toBe(false);
+    });
+
+    it('connects successfully', async () => {
+      await backend.connect();
+      expect(backend.isConnected()).toBe(true);
+    });
+
+    it('disconnects successfully', async () => {
+      await backend.connect();
+      backend.disconnect();
+      expect(backend.isConnected()).toBe(false);
+    });
+  });
+
+  describe('runtime.info', () => {
+    it('returns runtime info even when disconnected', async () => {
+      const req = makeRequest(OPS.RUNTIME_INFO, {});
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(true);
+      expect(res.result).toMatchObject({
+        runtime: 'demo',
+        engine_present: false,
+        mode: 'demo',
+      });
+    });
+  });
+
+  describe('auth.set', () => {
+    beforeEach(async () => {
+      await backend.connect();
+    });
+
+    it('sets auth context successfully', async () => {
+      const req = makeRequest(OPS.AUTH_SET, {
+        tenantId: 'tenant-123',
+        sub: 'user-456',
+        jwt: 'test-jwt',
+      });
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(true);
+    });
+
+    it('fails without required fields', async () => {
+      const req = makeRequest(OPS.AUTH_SET, { tenantId: 'test' });
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(false);
+      expect(res.error?.code).toBe('INVALID_PAYLOAD');
+    });
+
+    it('requires connection', async () => {
+      backend.disconnect();
+      const req = makeRequest(OPS.AUTH_SET, {
+        tenantId: 'tenant-123',
+        sub: 'user-456',
+        jwt: 'test-jwt',
+      });
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(false);
+      expect(res.error?.code).toBe('NOT_CONNECTED');
+    });
+  });
+
+  describe('home.status', () => {
+    beforeEach(async () => {
+      await backend.connect();
+    });
+
+    it('returns BOOTSTRAP_PRE_LOGIN before auth', async () => {
+      const req = makeRequest(OPS.HOME_STATUS, {});
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(true);
+      expect((res.result as Record<string, unknown>).state).toBe('BOOTSTRAP_PRE_LOGIN');
+      expect((res.result as Record<string, unknown>).grantPresent).toBe(false);
+    });
+
+    it('returns AUTHENTICATED_NO_HOME_GRANT after auth', async () => {
+      // Set auth first
+      await backend.request(
+        makeRequest(OPS.AUTH_SET, {
+          tenantId: 'tenant-123',
+          sub: 'user-456',
+          jwt: 'test-jwt',
+        })
+      );
+
+      const req = makeRequest(OPS.HOME_STATUS, {});
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(true);
+      expect((res.result as Record<string, unknown>).state).toBe('AUTHENTICATED_NO_HOME_GRANT');
+    });
+  });
+
+  describe('home.grant', () => {
+    beforeEach(async () => {
+      await backend.connect();
+    });
+
+    it('fails without auth', async () => {
+      const req = makeRequest(OPS.HOME_GRANT, {});
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(false);
+      expect(res.error?.code).toBe('NOT_AUTHENTICATED');
+    });
+
+    it('succeeds with auth', async () => {
+      // Set auth first
+      await backend.request(
+        makeRequest(OPS.AUTH_SET, {
+          tenantId: 'tenant-123',
+          sub: 'user-456',
+          jwt: 'test-jwt',
+        })
+      );
+
+      const req = makeRequest(OPS.HOME_GRANT, {});
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(true);
+      expect((res.result as Record<string, unknown>).success).toBe(true);
+      expect((res.result as Record<string, unknown>).grant_id).toBeDefined();
+    });
+
+    it('changes status to HOME_GRANTED', async () => {
+      // Set auth
+      await backend.request(
+        makeRequest(OPS.AUTH_SET, {
+          tenantId: 'tenant-123',
+          sub: 'user-456',
+          jwt: 'test-jwt',
+        })
+      );
+
+      // Request grant
+      await backend.request(makeRequest(OPS.HOME_GRANT, {}));
+
+      // Check status
+      const res = await backend.request(makeRequest(OPS.HOME_STATUS, {}));
+
+      expect(res.ok).toBe(true);
+      expect((res.result as Record<string, unknown>).state).toBe('HOME_GRANTED');
+      expect((res.result as Record<string, unknown>).grantPresent).toBe(true);
+    });
+  });
+
+  describe('unknown operation', () => {
+    beforeEach(async () => {
+      await backend.connect();
+    });
+
+    it('returns error for unknown op', async () => {
+      const req = makeRequest('unknown.op', {});
+      const res = await backend.request(req);
+
+      expect(res.ok).toBe(false);
+      expect(res.error?.code).toBe('INVALID_OP');
+    });
+  });
+});

package/template/src/ekka/audit/index.ts

@@ -0,0 +1,7 @@
+/**
+ * EKKA Audit Module
+ * Re-exports audit types and store functions.
+ */
+
+export * from './types';
+export * from './store';

package/template/src/ekka/audit/store.ts

@@ -0,0 +1,68 @@
+/**
+ * Audit Event Store
+ * In-memory store for audit events with subscription support.
+ */
+
+import type { AuditEvent } from './types';
+
+// In-memory event store
+const events: AuditEvent[] = [];
+const listeners: Set<() => void> = new Set();
+
+let eventCounter = 0;
+
+/**
+ * Generate a unique event ID.
+ */
+function generateEventId(): string {
+  eventCounter += 1;
+  return `evt_${Date.now()}_${eventCounter}`;
+}
+
+/**
+ * Notify all subscribers of a change.
+ */
+function notifyListeners(): void {
+  listeners.forEach((listener) => listener());
+}
+
+/**
+ * Add a new audit event to the store.
+ */
+export function addAuditEvent(
+  event: Omit<AuditEvent, 'id' | 'timestamp'>
+): void {
+  const fullEvent: AuditEvent = {
+    ...event,
+    id: generateEventId(),
+    timestamp: new Date(),
+  };
+  events.unshift(fullEvent); // Add to beginning (newest first)
+  notifyListeners();
+}
+
+/**
+ * Get all audit events (newest first).
+ */
+export function getAuditEvents(): AuditEvent[] {
+  return [...events];
+}
+
+/**
+ * Clear all audit events.
+ */
+export function clearAuditEvents(): void {
+  events.length = 0;
+  notifyListeners();
+}
+
+/**
+ * Subscribe to audit event changes.
+ * Returns an unsubscribe function.
+ */
+export function subscribeToAuditEvents(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/template/src/ekka/audit/types.ts

@@ -0,0 +1,22 @@
+/**
+ * Audit Event Types
+ * Type definitions for the audit logging system.
+ */
+
+/**
+ * Represents an audit event in the system.
+ */
+export interface AuditEvent {
+  /** Unique identifier for the event */
+  id: string;
+  /** When the event occurred */
+  timestamp: Date;
+  /** Event type (e.g., 'db.put', 'auth.login') */
+  type: string;
+  /** Human-readable description */
+  description: string;
+  /** Optional explanation for non-technical users */
+  explanation?: string;
+  /** Optional technical details for debugging */
+  technical?: Record<string, unknown>;
+}

package/template/src/ekka/auth/client.ts

@@ -0,0 +1,212 @@
+/**
+ * Auth API Client
+ *
+ * Handles authentication requests to the EKKA API.
+ * All HTTP proxied through Rust via engine_request.
+ */
+
+import { OPS } from '../constants';
+import { _internal, makeRequest } from '../internal';
+import type {
+  LoginResponse,
+  RefreshResponse,
+  AuthTokens,
+  UserInfo,
+} from './types';
+import {
+  setTokens,
+  clearTokens,
+  getRefreshToken,
+  getAccessToken,
+  setUser,
+  getUser,
+  clearUser,
+} from './storage';
+
+/**
+ * API request error with status code and error details.
+ */
+export class ApiRequestError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(message: string, status: number, code: string) {
+    super(message);
+    this.name = 'ApiRequestError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+
+/**
+ * Login with email/username and password.
+ * Stores tokens and user info on success.
+ *
+ * @throws ApiRequestError on authentication failure
+ */
+export async function login(identifier: string, password: string): Promise<LoginResponse> {
+  const req = makeRequest(OPS.AUTH_LOGIN, {
+    identifier,
+    password,
+  });
+
+  const engineResponse = await _internal.request(req);
+
+  if (!engineResponse.ok) {
+    const error = engineResponse.error;
+    throw new ApiRequestError(
+      error?.message || 'Login failed',
+      error?.status || 401,
+      error?.code || 'AUTH_ERROR'
+    );
+  }
+
+  const response = engineResponse.result as LoginResponse;
+
+  // Store tokens and user
+  setTokens({
+    access_token: response.access_token,
+    refresh_token: response.refresh_token,
+  });
+  setUser(response.user);
+
+  // Notify listeners
+  notifyAuthChange(true);
+
+  return response;
+}
+
+/**
+ * Refresh the access token using the stored refresh token.
+ * Stores new tokens on success.
+ *
+ * @throws Error if no refresh token available
+ * @throws ApiRequestError if refresh fails
+ */
+export async function refresh(): Promise<AuthTokens> {
+  const refreshToken = getRefreshToken();
+
+  if (!refreshToken) {
+    throw new Error('No refresh token available');
+  }
+
+  const req = makeRequest(OPS.AUTH_REFRESH, {
+    refresh_token: refreshToken,
+    jwt: getAccessToken(), // Include current access token if available
+  });
+
+  try {
+    const engineResponse = await _internal.request(req);
+
+    if (!engineResponse.ok) {
+      const error = engineResponse.error;
+      throw new ApiRequestError(
+        error?.message || 'Token refresh failed',
+        error?.status || 401,
+        error?.code || 'AUTH_ERROR'
+      );
+    }
+
+    const response = engineResponse.result as RefreshResponse;
+
+    // Store new tokens
+    setTokens({
+      access_token: response.access_token,
+      refresh_token: response.refresh_token,
+    });
+
+    // Notify listeners
+    notifyAuthChange(true);
+
+    return {
+      access_token: response.access_token,
+      refresh_token: response.refresh_token,
+    };
+  } catch (error) {
+    // Clear tokens on refresh failure (session expired)
+    clearTokens();
+    clearUser();
+    notifyAuthChange(false);
+    throw error;
+  }
+}
+
+/**
+ * Logout the current user.
+ * Clears all stored tokens and user info.
+ */
+export async function logout(): Promise<void> {
+  const refreshToken = getRefreshToken();
+
+  // Attempt to notify server (best effort)
+  if (refreshToken) {
+    try {
+      const req = makeRequest(OPS.AUTH_LOGOUT, {
+        refresh_token: refreshToken,
+      });
+      await _internal.request(req);
+    } catch {
+      // Ignore server errors during logout
+    }
+  }
+
+  // Always clear local state
+  clearTokens();
+  clearUser();
+  notifyAuthChange(false);
+}
+
+/**
+ * Check if user is currently authenticated.
+ */
+export function isAuthenticated(): boolean {
+  return getAccessToken() !== null;
+}
+
+/**
+ * Get current user info.
+ */
+export function getCurrentUser(): UserInfo | null {
+  return getUser();
+}
+
+// =============================================================================
+// AUTH STATE CHANGE LISTENERS
+// =============================================================================
+
+type AuthChangeListener = (isAuthenticated: boolean) => void;
+const authChangeListeners: Set<AuthChangeListener> = new Set();
+
+/**
+ * Subscribe to authentication state changes.
+ * Returns an unsubscribe function.
+ */
+export function onAuthChange(listener: AuthChangeListener): () => void {
+  authChangeListeners.add(listener);
+  return () => {
+    authChangeListeners.delete(listener);
+  };
+}
+
+/**
+ * Notify all listeners of auth state change.
+ */
+function notifyAuthChange(isAuthenticated: boolean): void {
+  authChangeListeners.forEach((listener) => {
+    try {
+      listener(isAuthenticated);
+    } catch {
+      // Ignore listener errors
+    }
+  });
+}
+
+// =============================================================================
+// RE-EXPORTS
+// =============================================================================
+
+export type { UserInfo, AuthTokens } from './types';

package/template/src/ekka/auth/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Auth Module Exports
+ *
+ * Public API for authentication.
+ */
+
+// Types
+export type {
+  LoginRequest,
+  LoginResponse,
+  RefreshRequest,
+  RefreshResponse,
+  AuthTokens,
+  AuthState,
+  UserInfo,
+} from './types';
+
+// Client functions
+export {
+  login,
+  logout,
+  refresh,
+  isAuthenticated,
+  getCurrentUser,
+  onAuthChange,
+  ApiRequestError,
+} from './client';
+
+// Storage helpers
+export { getAccessToken, hasStoredRefreshToken } from './storage';

package/template/src/ekka/auth/storage.ts

@@ -0,0 +1,114 @@
+/**
+ * Token & User Storage
+ *
+ * Memory storage for access token (secure - never persisted)
+ * localStorage for refresh token (persistent across sessions)
+ * localStorage for user info (persistent across sessions)
+ */
+
+import type { AuthTokens, UserInfo } from './types';
+
+// =============================================================================
+// STORAGE KEYS
+// =============================================================================
+
+const REFRESH_TOKEN_KEY = 'ekka.auth.refresh_token';
+const USER_KEY = 'ekka.auth.user';
+
+// =============================================================================
+// IN-MEMORY TOKEN STORAGE
+// =============================================================================
+
+// Access token stored in memory only (never persisted to disk)
+let accessToken: string | null = null;
+
+// =============================================================================
+// TOKEN FUNCTIONS
+// =============================================================================
+
+/**
+ * Store authentication tokens.
+ * Access token in memory, refresh token in localStorage.
+ */
+export function setTokens(tokens: AuthTokens): void {
+  accessToken = tokens.access_token;
+
+  if (typeof localStorage !== 'undefined') {
+    localStorage.setItem(REFRESH_TOKEN_KEY, tokens.refresh_token);
+  }
+}
+
+/**
+ * Get the current access token from memory.
+ */
+export function getAccessToken(): string | null {
+  return accessToken;
+}
+
+/**
+ * Get the refresh token from localStorage.
+ */
+export function getRefreshToken(): string | null {
+  if (typeof localStorage === 'undefined') {
+    return null;
+  }
+  return localStorage.getItem(REFRESH_TOKEN_KEY);
+}
+
+/**
+ * Clear all tokens.
+ */
+export function clearTokens(): void {
+  accessToken = null;
+
+  if (typeof localStorage !== 'undefined') {
+    localStorage.removeItem(REFRESH_TOKEN_KEY);
+  }
+}
+
+/**
+ * Check if a refresh token exists in localStorage.
+ */
+export function hasStoredRefreshToken(): boolean {
+  return getRefreshToken() !== null;
+}
+
+// =============================================================================
+// USER FUNCTIONS
+// =============================================================================
+
+/**
+ * Store user info in localStorage.
+ */
+export function setUser(user: UserInfo): void {
+  if (typeof localStorage !== 'undefined') {
+    localStorage.setItem(USER_KEY, JSON.stringify(user));
+  }
+}
+
+/**
+ * Get user info from localStorage.
+ */
+export function getUser(): UserInfo | null {
+  if (typeof localStorage === 'undefined') {
+    return null;
+  }
+  const stored = localStorage.getItem(USER_KEY);
+  if (!stored) {
+    return null;
+  }
+  try {
+    return JSON.parse(stored) as UserInfo;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clear user info.
+ */
+export function clearUser(): void {
+  if (typeof localStorage !== 'undefined') {
+    localStorage.removeItem(USER_KEY);
+  }
+}

package/template/src/ekka/auth/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Auth Types
+ *
+ * Type definitions for authentication system.
+ */
+
+// =============================================================================
+// REQUEST TYPES
+// =============================================================================
+
+export interface LoginRequest {
+  identifier: string; // Email or username
+  password: string;
+}
+
+export interface RefreshRequest {
+  refresh_token: string;
+}
+
+export interface LogoutRequest {
+  refresh_token: string;
+}
+
+// =============================================================================
+// RESPONSE TYPES
+// =============================================================================
+
+export interface UserInfo {
+  id: string;
+  email: string;
+  name: string | null;
+  avatar_url: string | null;
+  role: string;
+  company?: {
+    id: string;
+    name: string;
+  };
+}
+
+export interface LoginResponse {
+  user: UserInfo;
+  access_token: string;
+  refresh_token: string;
+}
+
+export interface RefreshResponse {
+  access_token: string;
+  refresh_token: string;
+}
+
+export interface LogoutResponse {
+  message: string;
+}
+
+// =============================================================================
+// INTERNAL TYPES
+// =============================================================================
+
+export interface AuthTokens {
+  access_token: string;
+  refresh_token: string;
+}
+
+export interface AuthState {
+  isAuthenticated: boolean;
+  user: UserInfo | null;
+}