create-ekka-desktop-app 0.2.2

package/template/src/ekka/index.ts

@@ -0,0 +1,516 @@
+/**
+ * EKKA Client
+ *
+ * Simple API for frontend developers.
+ *
+ * @example
+ * ```typescript
+ * import { ekka } from '@ekka/client';
+ *
+ * // Connect and setup
+ * await ekka.connect();
+ * await ekka.auth.login('user@example.com', 'password');
+ * await ekka.home.setup();
+ *
+ * // Check status
+ * const ready = await ekka.home.isReady();
+ * ```
+ */
+
+import { _internal } from './internal';
+import * as authClient from './auth/client';
+import * as ops from './ops';
+
+// =============================================================================
+// SIMPLE API (for most developers)
+// =============================================================================
+
+export const ekka = {
+  // ---------------------------------------------------------------------------
+  // Setup (pre-login device configuration)
+  // ---------------------------------------------------------------------------
+
+  setup: {
+    /**
+     * Get setup status.
+     * Call before login to check if setup wizard is needed.
+     * Returns { nodeIdentity, setupComplete }
+     * Home folder grant is handled post-login via HomeSetupPage.
+     */
+    status: () => ops.setup.status(),
+  },
+
+  // ---------------------------------------------------------------------------
+  // Connection
+  // ---------------------------------------------------------------------------
+
+  /** Connect to EKKA. Call this first. */
+  connect: () => _internal.connect(),
+
+  /** Disconnect from EKKA. */
+  disconnect: () => _internal.disconnect(),
+
+  /** Check if connected. */
+  isConnected: () => _internal.isConnected(),
+
+  // ---------------------------------------------------------------------------
+  // Node Credentials (headless engine startup)
+  // ---------------------------------------------------------------------------
+
+  nodeCredentials: {
+    /**
+     * Set node credentials.
+     * Stores node_id + node_secret in OS keychain.
+     * Validates UUID format and secret length.
+     */
+    set: (nodeId: string, nodeSecret: string) =>
+      ops.nodeCredentials.set({ nodeId, nodeSecret }),
+
+    /**
+     * Get credentials status.
+     * Returns { hasCredentials, nodeId } - does NOT return secret.
+     */
+    status: () => ops.nodeCredentials.status(),
+
+    /**
+     * Clear credentials from keychain.
+     */
+    clear: () => ops.nodeCredentials.clear(),
+
+    /**
+     * Validate node_id format (UUID).
+     */
+    isValidNodeId: ops.nodeCredentials.isValidNodeId,
+
+    /**
+     * Validate node_secret format.
+     */
+    isValidNodeSecret: ops.nodeCredentials.isValidNodeSecret,
+  },
+
+  // ---------------------------------------------------------------------------
+  // Auth (simple - login/logout)
+  // ---------------------------------------------------------------------------
+
+  auth: {
+    /**
+     * Login with email and password.
+     * Handles HTTP auth + engine context setup + node session bootstrap automatically.
+     *
+     * After login:
+     * 1. Sets engine auth context
+     * 2. Bootstraps node session (Ed25519 challenge/response)
+     * 3. Starts the runner automatically
+     */
+    login: async (identifier: string, password: string): Promise<void> => {
+      const response = await authClient.login(identifier, password);
+
+      // Set engine auth context
+      const tenantId = response.user.company?.id || 'default';
+      const sub = response.user.id;
+      const jwt = response.access_token;
+
+      // Use tenant_id as default workspace_id (can be overridden later)
+      // TODO: Get workspace_id from JWT claims or user selection
+      const workspaceId = tenantId;
+
+      await ops.auth.setContext({ tenantId, sub, jwt, workspaceId });
+
+      // Bootstrap node session and start runner
+      try {
+        await ops.nodeSession.bootstrap({ startRunner: true });
+      } catch (e) {
+        // Log but don't fail login - runner can be started later
+        console.warn('[ekka] Node session bootstrap failed:', e);
+      }
+    },
+
+    /** Logout and clear session. */
+    logout: async (): Promise<void> => {
+      await authClient.logout();
+    },
+
+    /** Check if logged in. */
+    isLoggedIn: (): boolean => authClient.isAuthenticated(),
+
+    /** Get current user info. */
+    user: (): authClient.UserInfo | null => authClient.getCurrentUser(),
+  },
+
+  // ---------------------------------------------------------------------------
+  // Home (simple - setup/isReady)
+  // ---------------------------------------------------------------------------
+
+  home: {
+    /**
+     * Set up home directory.
+     * Just call this after login - it handles everything.
+     */
+    setup: () => ops.home.setup(),
+
+    /**
+     * Check if home is ready.
+     * Returns true/false - no scary state machines.
+     */
+    isReady: () => ops.home.isReady(),
+  },
+
+  // ---------------------------------------------------------------------------
+  // Paths (simple - check/allow access)
+  // ---------------------------------------------------------------------------
+
+  paths: {
+    /**
+     * Check if an operation is allowed on a path.
+     * Returns true/false - simple boolean.
+     */
+    isAllowed: (path: string, operation?: string) =>
+      ops.paths.isAllowed(path, operation),
+
+    /**
+     * List all path grants.
+     */
+    list: (type?: ops.paths.PathType) => ops.paths.list(type),
+
+    /**
+     * Get information about a specific path.
+     */
+    get: (path: string) => ops.paths.get(path),
+
+    /**
+     * Allow access to a path.
+     * Requests a grant from the engine.
+     */
+    allow: (path: string, options?: ops.paths.PathRequestOptions) =>
+      ops.paths.allow(path, options),
+
+    /**
+     * Remove a path grant.
+     */
+    remove: (path: string) => ops.paths.remove(path),
+  },
+
+  // ---------------------------------------------------------------------------
+  // Vault (status, secrets, bundles, files, audit)
+  // SECURITY: Secret values are NEVER returned by the API.
+  // ---------------------------------------------------------------------------
+
+  vault: {
+    /** Get vault status */
+    status: () => ops.vault.status(),
+
+    /** Get vault capabilities */
+    capabilities: () => ops.vault.capabilities(),
+
+    /**
+     * Secret operations (metadata only - values never returned)
+     */
+    secrets: {
+      /** List all secrets (metadata only, NO values) */
+      list: (opts?: ops.vault.SecretListOptions) => ops.vault.secrets.list(opts),
+      /** Get a secret by ID (metadata only, NO value) */
+      get: (id: string) => ops.vault.secrets.get(id),
+      /** Create a new secret (value accepted here only) */
+      create: (input: ops.vault.SecretCreateInput) => ops.vault.secrets.create(input),
+      /** Update a secret (value accepted here only) */
+      update: (id: string, input: ops.vault.SecretUpdateInput) => ops.vault.secrets.update(id, input),
+      /** Delete a secret */
+      delete: (id: string) => ops.vault.secrets.delete(id),
+      /** Upsert a secret (create or update by name) */
+      upsert: (input: ops.vault.SecretCreateInput) => ops.vault.secrets.upsert(input),
+    },
+
+    /**
+     * Bundle operations (groups of related secrets)
+     */
+    bundles: {
+      /** List all bundles */
+      list: (opts?: ops.vault.BundleListOptions) => ops.vault.bundles.list(opts),
+      /** Get a bundle by ID */
+      get: (id: string) => ops.vault.bundles.get(id),
+      /** Create a new bundle */
+      create: (input: ops.vault.BundleCreateInput) => ops.vault.bundles.create(input),
+      /** Rename a bundle */
+      rename: (id: string, name: string) => ops.vault.bundles.rename(id, name),
+      /** Delete a bundle */
+      delete: (id: string) => ops.vault.bundles.delete(id),
+      /** List secrets in a bundle */
+      listSecrets: (bundleId: string, opts?: ops.vault.SecretListOptions) => ops.vault.bundles.listSecrets(bundleId, opts),
+      /** Add a secret to a bundle */
+      addSecret: (bundleId: string, secretId: string) => ops.vault.bundles.addSecret(bundleId, secretId),
+      /** Remove a secret from a bundle */
+      removeSecret: (bundleId: string, secretId: string) => ops.vault.bundles.removeSecret(bundleId, secretId),
+    },
+
+    /**
+     * Files operations (encrypted file storage)
+     * Paths are relative to workspace root. Chroot enforced.
+     */
+    files: {
+      /** Write text content to a file */
+      writeText: (path: string, content: string, opts?: ops.vault.FileOptions) =>
+        ops.vault.files.writeText(path, content, opts),
+      /** Write binary content to a file (content as base64) */
+      writeBytes: (path: string, contentBytes: string, opts?: ops.vault.FileOptions) =>
+        ops.vault.files.writeBytes(path, contentBytes, opts),
+      /** Read text content from a file */
+      readText: (path: string, opts?: ops.vault.FileOptions) =>
+        ops.vault.files.readText(path, opts),
+      /** Read binary content from a file (returns base64) */
+      readBytes: (path: string, opts?: ops.vault.FileOptions) =>
+        ops.vault.files.readBytes(path, opts),
+      /** List files and directories */
+      list: (dir: string, opts?: ops.vault.FileListOptions) =>
+        ops.vault.files.list(dir, opts),
+      /** Check if a file or directory exists */
+      exists: (path: string, opts?: ops.vault.FileOptions) =>
+        ops.vault.files.exists(path, opts),
+      /** Delete a file or directory */
+      delete: (path: string, opts?: ops.vault.FileDeleteOptions) =>
+        ops.vault.files.delete(path, opts),
+      /** Create a directory */
+      mkdir: (path: string, opts?: ops.vault.FileOptions) =>
+        ops.vault.files.mkdir(path, opts),
+      /** Move a file or directory */
+      move: (from: string, to: string, opts?: ops.vault.FileOptions) =>
+        ops.vault.files.move(from, to, opts),
+    },
+
+    /**
+     * Attach secrets to a connector (DEFERRED - returns NOT_IMPLEMENTED)
+     */
+    attachSecretsToConnector: (connectorId: string, mappings: ops.vault.SecretRef[]) =>
+      ops.vault.attachSecretsToConnector(connectorId, mappings),
+
+    /**
+     * Inject secrets into a run (DEFERRED - returns NOT_IMPLEMENTED)
+     */
+    injectSecretsIntoRun: (runId: string, mappings: ops.vault.SecretRef[]) =>
+      ops.vault.injectSecretsIntoRun(runId, mappings),
+
+    /**
+     * Audit log operations (cursor-based pagination)
+     */
+    audit: {
+      /** List audit events */
+      list: (opts?: ops.vault.AuditListOptions) => ops.vault.audit.list(opts),
+    },
+  },
+};
+
+// =============================================================================
+// ADVANCED API (for power users)
+// =============================================================================
+
+export const advanced = {
+  /**
+   * Auth operations (low-level)
+   */
+  auth: {
+    /** Set engine auth context directly. */
+    setContext: ops.auth.setContext,
+
+    /** Refresh access token. */
+    refresh: authClient.refresh,
+
+    /** Subscribe to auth state changes. */
+    onAuthChange: authClient.onAuthChange,
+  },
+
+  /**
+   * Home operations (low-level)
+   */
+  home: {
+    /** Get raw home status (state machine). */
+    status: ops.home.status,
+
+    /** Request home grant manually. */
+    grant: ops.home.grant,
+  },
+
+  /**
+   * Paths operations (low-level)
+   */
+  paths: {
+    /** Check if operation is allowed (with details). */
+    check: ops.paths.check,
+
+    /** List all path grants. */
+    list: ops.paths.list,
+
+    /** Get path info. */
+    get: ops.paths.get,
+
+    /** Request path access. */
+    request: ops.paths.request,
+
+    /** Remove path grant. */
+    remove: ops.paths.remove,
+  },
+
+  /**
+   * Runtime operations
+   */
+  runtime: {
+    /** Get runtime info. */
+    info: ops.runtime.info,
+  },
+
+  /**
+   * Runner operations (local runner status + task queue stats)
+   */
+  runner: {
+    /** Get local runner status for this desktop instance. */
+    status: ops.runner.status,
+    /** Get task queue stats from engine API (proxied via Rust). */
+    taskStats: ops.runner.taskStats,
+  },
+
+  /**
+   * Node session operations (Ed25519-based authentication)
+   */
+  nodeSession: {
+    /** Ensure node identity exists (keypair generation). No auth required. */
+    ensureIdentity: ops.nodeSession.ensureIdentity,
+    /** Bootstrap full node session. Requires user to be logged in. */
+    bootstrap: ops.nodeSession.bootstrap,
+    /** Get current node session status. */
+    status: ops.nodeSession.status,
+  },
+
+  /**
+   * Node credentials operations (keychain-stored)
+   */
+  nodeCredentials: {
+    /** Set node credentials in keychain. */
+    set: ops.nodeCredentials.set,
+    /** Get credentials status. */
+    status: ops.nodeCredentials.status,
+    /** Clear credentials from keychain. */
+    clear: ops.nodeCredentials.clear,
+  },
+
+  /**
+   * Vault operations (low-level)
+   */
+  vault: {
+    /** Vault status */
+    status: ops.vault.status,
+    /** Vault capabilities */
+    capabilities: ops.vault.capabilities,
+    /** Secret operations (metadata only) */
+    secrets: ops.vault.secrets,
+    /** Bundle operations */
+    bundles: ops.vault.bundles,
+    /** Files operations */
+    files: ops.vault.files,
+    /** Attach secrets to connector */
+    attachSecretsToConnector: ops.vault.attachSecretsToConnector,
+    /** Inject secrets into run */
+    injectSecretsIntoRun: ops.vault.injectSecretsIntoRun,
+    /** Audit operations */
+    audit: ops.vault.audit,
+  },
+
+  /**
+   * Internal backend access
+   */
+  internal: {
+    /** Get current transport mode. */
+    mode: () => _internal.getMode(),
+  },
+};
+
+// =============================================================================
+// TYPE EXPORTS
+// =============================================================================
+
+export type { SetupState, SetupStatus } from './ops/setup';
+export type { HomeState, HomeStatus, GrantResult } from './ops/home';
+export type {
+  PathType,
+  PathAccess,
+  PathInfo,
+  PathCheckResult,
+  PathGrantResult,
+  PathRequestOptions,
+} from './ops/paths';
+export type { RuntimeInfo } from './ops/runtime';
+export type { RunnerStatus, RunnerLoopState, RunnerTaskStats } from './ops/runner';
+export type { AuthContext } from './ops/auth';
+export type {
+  NodeIdentity,
+  EnsureIdentityResult,
+  BootstrapOptions,
+  BootstrapResult,
+  SessionInfo,
+  NodeSessionStatus,
+} from './ops/nodeSession';
+export type {
+  SetCredentialsInput,
+  SetCredentialsResult,
+  CredentialsStatus,
+  NodeAuthSession,
+} from './ops/nodeCredentials';
+export type { UserInfo, AuthTokens } from './auth/types';
+export type { TransportMode } from './internal';
+
+// Vault types
+export type {
+  VaultStatus,
+  VaultCapabilities,
+  SecretType,
+  SecretMeta,
+  SecretCreateInput,
+  SecretUpdateInput,
+  SecretListOptions,
+  BundleMeta,
+  BundleCreateInput,
+  BundleListOptions,
+  FileKind,
+  FileEntry,
+  FileOptions,
+  FileListOptions,
+  FileDeleteOptions,
+  SecretInjection,
+  SecretRef,
+  AuditAction,
+  AuditEvent,
+  AuditListOptions,
+  AuditListResult,
+} from './ops/vault';
+
+// =============================================================================
+// ERROR EXPORTS
+// =============================================================================
+
+export {
+  EkkaError,
+  EkkaNotConnectedError,
+  EkkaConnectionError,
+  EkkaApiError,
+} from './errors';
+
+// =============================================================================
+// UTILITIES (optional helpers)
+// =============================================================================
+
+export {
+  formatRelativeTime,
+  formatLocalTime,
+  formatExpiryInfo,
+} from './utils/time';
+
+export { generateIdempotencyKey } from './utils/idempotency';
+
+// =============================================================================
+// AUDIT (client-side event logging)
+// =============================================================================
+
+export type { AuditEvent as ClientAuditEvent } from './audit/types';
+export {
+  addAuditEvent,
+  getAuditEvents,
+  clearAuditEvents,
+  subscribeToAuditEvents,
+} from './audit/store';

package/template/src/ekka/internal/backend.ts

@@ -0,0 +1,156 @@
+/**
+ * EKKA Internal Backend
+ *
+ * SmartBackend auto-detects engine vs demo mode on connect.
+ * This module is NOT exported publicly - only accessible via _internal.
+ */
+
+import type { EngineRequest, EngineResponse } from '../types';
+import { err, makeRequest } from '../types';
+import { DemoBackend } from '../backend/demo';
+
+/**
+ * Transport mode - determined on connect.
+ */
+export type TransportMode = 'unknown' | 'engine' | 'demo';
+
+/**
+ * SmartBackend - single backend that auto-detects engine vs demo.
+ *
+ * On connect():
+ * - Tries to connect to Tauri engine
+ * - If successful: engine mode
+ * - If fails: demo mode (in-memory)
+ */
+class SmartBackend {
+  private mode: TransportMode = 'unknown';
+  private connected = false;
+  private demoBackend = new DemoBackend();
+
+  /**
+   * Connect to the backend.
+   * Auto-detects engine vs demo mode.
+   */
+  async connect(): Promise<void> {
+    if (this.connected) return;
+
+    // Try engine first (only works in Tauri with engine present)
+    try {
+      const { invoke } = await import('@tauri-apps/api/core');
+      await invoke('engine_connect');
+      this.mode = 'engine';
+      this.connected = true;
+      return;
+    } catch {
+      // Engine not available - use demo mode
+    }
+
+    // Fall back to demo mode
+    this.mode = 'demo';
+    await this.demoBackend.connect();
+    this.connected = true;
+  }
+
+  /**
+   * Disconnect from the backend.
+   */
+  disconnect(): void {
+    if (!this.connected) return;
+
+    if (this.mode === 'engine') {
+      // Fire and forget
+      import('@tauri-apps/api/core')
+        .then(({ invoke }) => invoke('engine_disconnect'))
+        .catch(() => {});
+    } else {
+      this.demoBackend.disconnect();
+    }
+
+    this.connected = false;
+    this.mode = 'unknown';
+  }
+
+  /**
+   * Check if connected.
+   */
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  /**
+   * Get current transport mode.
+   */
+  getMode(): TransportMode {
+    return this.mode;
+  }
+
+  /**
+   * Send a request to the backend.
+   */
+  async request(req: EngineRequest): Promise<EngineResponse> {
+    // LOCAL-ONLY OPERATIONS: Always route to Tauri, never to demo backend
+    // These are desktop-specific operations that must be handled by Rust handlers
+    const localOnlyOps = [
+      'setup.status',
+      'nodeCredentials.set',
+      'nodeCredentials.status',
+      'nodeCredentials.clear',
+    ];
+
+    const isLocalOnlyOp = localOnlyOps.includes(req.op);
+
+    // Local-only ops ALWAYS go to Tauri - regardless of connection state or mode
+    // This ensures setup operations never accidentally route to demo backend
+    if (isLocalOnlyOp) {
+      console.log(`[ts.op.dispatch] op=${req.op} backend=tauri (local-only)`);
+      try {
+        const { invoke } = await import('@tauri-apps/api/core');
+        return await invoke<EngineResponse>('engine_request', { req });
+      } catch (e) {
+        const message = e instanceof Error ? e.message : 'Tauri not available';
+        console.error(`[ts.op.dispatch] op=${req.op} backend=tauri FAILED: ${message}`);
+        return err('TAURI_NOT_READY', message);
+      }
+    }
+
+    if (!this.connected) {
+      return err('NOT_CONNECTED', 'Not connected. Call ekka.connect() first.');
+    }
+
+    console.log(`[ts.op.dispatch] op=${req.op} backend=${this.mode} connected=${this.connected}`);
+
+    if (this.mode === 'engine') {
+      try {
+        const { invoke } = await import('@tauri-apps/api/core');
+        return await invoke<EngineResponse>('engine_request', { req });
+      } catch (e) {
+        const message = e instanceof Error ? e.message : 'Unknown invoke error';
+        return err('INTERNAL_ERROR', message);
+      }
+    }
+
+    // Demo mode
+    return this.demoBackend.request(req);
+  }
+}
+
+// =============================================================================
+// INTERNAL API (not exported from package)
+// =============================================================================
+
+const backend = new SmartBackend();
+
+/**
+ * Internal API - only accessible within the ekka package.
+ * NOT exported from the main index.ts.
+ */
+export const _internal = {
+  connect: () => backend.connect(),
+  disconnect: () => backend.disconnect(),
+  isConnected: () => backend.isConnected(),
+  getMode: () => backend.getMode(),
+  request: (req: EngineRequest) => backend.request(req),
+};
+
+// Re-export makeRequest for use by index.ts
+export { makeRequest };

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

@@ -0,0 +1,7 @@
+/**
+ * EKKA Internal Module
+ *
+ * Internal implementation details - NOT exported from package.
+ */
+
+export { _internal, makeRequest, type TransportMode } from './backend';

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

@@ -0,0 +1,29 @@
+/**
+ * Auth Operations
+ *
+ * Wraps Rust ops/auth.rs
+ */
+
+import { OPS } from '../constants';
+import { _internal, makeRequest } from '../internal';
+
+export interface AuthContext {
+  tenantId: string;
+  sub: string;
+  jwt: string;
+  /** Workspace ID (required for node session registration) */
+  workspaceId?: string;
+}
+
+/**
+ * Set authentication context in engine.
+ * Maps to Rust: auth.set
+ */
+export async function setContext(ctx: AuthContext): Promise<void> {
+  const req = makeRequest(OPS.AUTH_SET, ctx);
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to set auth context');
+  }
+}