create-ekka-desktop-app 0.2.2

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

@@ -0,0 +1,68 @@
+/**
+ * Debug Operations
+ *
+ * Utility operations for development and debugging.
+ * Only available when EKKA_ENV=development.
+ */
+
+import { _internal, makeRequest } from '../internal';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface DebugBundleInfo {
+  debug_bundle_ref: string;
+  raw_output_sha256: string;
+  raw_output_len: number;
+  files: string[];
+}
+
+export interface ResolvedVaultPath {
+  vaultUri: string;
+  filesystemPath: string;
+  exists: boolean;
+}
+
+// =============================================================================
+// Operations
+// =============================================================================
+
+/**
+ * Check if running in development mode.
+ */
+export async function isDevMode(): Promise<boolean> {
+  const req = makeRequest('debug.isDevMode', {});
+  const response = await _internal.request(req);
+  const result = response.result as { isDevMode?: boolean } | undefined;
+  return result?.isDevMode ?? false;
+}
+
+/**
+ * Open a folder in the system file browser.
+ * Only works in development mode.
+ *
+ * @param path - Path to open (supports vault:// URIs)
+ */
+export async function openFolder(path: string): Promise<void> {
+  const req = makeRequest('debug.openFolder', { path });
+  const response = await _internal.request(req);
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to open folder');
+  }
+}
+
+/**
+ * Resolve a vault:// URI to filesystem path.
+ * Only works in development mode.
+ *
+ * @param vaultUri - Vault URI (e.g., "vault://tmp/telemetry/...")
+ */
+export async function resolveVaultPath(vaultUri: string): Promise<ResolvedVaultPath> {
+  const req = makeRequest('debug.resolveVaultPath', { path: vaultUri });
+  const response = await _internal.request(req);
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to resolve vault path');
+  }
+  return response.result as ResolvedVaultPath;
+}

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

@@ -0,0 +1,101 @@
+/**
+ * Home Operations
+ *
+ * Wraps Rust ops/home.rs
+ */
+
+import { OPS } from '../constants';
+import { _internal, makeRequest } from '../internal';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type HomeState =
+  | 'BOOTSTRAP_PRE_LOGIN'
+  | 'AUTHENTICATED_NO_HOME_GRANT'
+  | 'HOME_GRANTED';
+
+export interface HomeStatus {
+  state: HomeState;
+  homePath: string;
+  grantPresent: boolean;
+  reason: string | null;
+}
+
+export interface GrantResult {
+  success: boolean;
+  grant_id: string;
+  expires_at: string | null;
+}
+
+// =============================================================================
+// Raw Operations (Advanced API)
+// =============================================================================
+
+/**
+ * Get home directory status.
+ * Maps to Rust: home.status
+ */
+export async function status(): Promise<HomeStatus> {
+  const req = makeRequest(OPS.HOME_STATUS, {});
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to get home status');
+  }
+
+  return response.result as HomeStatus;
+}
+
+/**
+ * Request HOME grant from engine.
+ * Maps to Rust: home.grant
+ */
+export async function grant(): Promise<GrantResult> {
+  const req = makeRequest(OPS.HOME_GRANT, {});
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to request grant');
+  }
+
+  return response.result as GrantResult;
+}
+
+// =============================================================================
+// Simple Operations (Public API)
+// =============================================================================
+
+/**
+ * Check if home is ready to use.
+ * Simple boolean - no scary state machines.
+ */
+export async function isReady(): Promise<boolean> {
+  try {
+    const s = await status();
+    return s.state === 'HOME_GRANTED';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Set up home directory.
+ * Does everything needed - checks status, requests grant if needed.
+ * Just call this and you're done.
+ */
+export async function setup(): Promise<void> {
+  const s = await status();
+
+  if (s.state === 'HOME_GRANTED') {
+    return; // Already ready
+  }
+
+  if (s.state === 'BOOTSTRAP_PRE_LOGIN') {
+    throw new Error('Please login first before setting up home');
+  }
+
+  // State is AUTHENTICATED_NO_HOME_GRANT - request the grant
+  await grant();
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Operations
+ *
+ * Mirrors Rust src-tauri/src/ops/ and handlers/
+ */
+
+export * as auth from './auth';
+export * as debug from './debug';
+export * as home from './home';
+export * as paths from './paths';
+export * as runtime from './runtime';
+export * as runner from './runner';
+export * as setup from './setup';
+export * as vault from './vault';
+export * as nodeSession from './nodeSession';
+export * as nodeCredentials from './nodeCredentials';

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

@@ -0,0 +1,131 @@
+/**
+ * Node Credentials Operations
+ *
+ * Manages node_id + node_secret for headless engine startup.
+ * Credentials are stored securely in OS keychain.
+ *
+ * ## Usage
+ * 1. User provides node_id + node_secret once (onboarding)
+ * 2. Credentials stored in OS keychain
+ * 3. Engine uses them automatically on startup (no login required)
+ */
+
+import { OPS } from '../constants';
+import { _internal, makeRequest } from '../internal';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Input for setting node credentials */
+export interface SetCredentialsInput {
+  nodeId: string;
+  nodeSecret: string;
+}
+
+/** Result from setting credentials */
+export interface SetCredentialsResult {
+  ok: boolean;
+  nodeId: string;
+}
+
+/** Auth session info from node authentication */
+export interface NodeAuthSession {
+  sessionId: string;
+  tenantId: string;
+  workspaceId: string;
+  expiresAt: string;
+}
+
+/** Credentials status */
+export interface CredentialsStatus {
+  hasCredentials: boolean;
+  nodeId: string | null;
+  isAuthenticated: boolean;
+  authSession: NodeAuthSession | null;
+}
+
+// =============================================================================
+// OPERATIONS
+// =============================================================================
+
+/**
+ * Set node credentials.
+ *
+ * Stores node_id + node_secret in OS keychain.
+ * Validates:
+ * - node_id must be valid UUID
+ * - node_secret must be non-empty and at least 16 characters
+ *
+ * @param input - { nodeId: UUID, nodeSecret: string }
+ * @returns { ok: true, nodeId: string } on success
+ * @throws Error if validation fails or keychain error
+ */
+export async function set(input: SetCredentialsInput): Promise<SetCredentialsResult> {
+  const req = makeRequest(OPS.NODE_CREDENTIALS_SET, {
+    nodeId: input.nodeId,
+    nodeSecret: input.nodeSecret,
+  });
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to store node credentials');
+  }
+
+  return response.result as SetCredentialsResult;
+}
+
+/**
+ * Get credentials status.
+ *
+ * Returns whether credentials are configured and the node_id (if present).
+ * Does NOT return the node_secret.
+ */
+export async function status(): Promise<CredentialsStatus> {
+  const req = makeRequest(OPS.NODE_CREDENTIALS_STATUS, {});
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to get credentials status');
+  }
+
+  return response.result as CredentialsStatus;
+}
+
+/**
+ * Clear node credentials from OS keychain.
+ *
+ * @returns { ok: true } on success
+ */
+export async function clear(): Promise<{ ok: boolean }> {
+  const req = makeRequest(OPS.NODE_CREDENTIALS_CLEAR, {});
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to clear credentials');
+  }
+
+  return response.result as { ok: boolean };
+}
+
+/**
+ * Validate node_id format (UUID).
+ *
+ * @param nodeId - String to validate
+ * @returns true if valid UUID format
+ */
+export function isValidNodeId(nodeId: string): boolean {
+  const uuidRegex =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  return uuidRegex.test(nodeId);
+}
+
+/**
+ * Validate node_secret format.
+ *
+ * @param nodeSecret - String to validate
+ * @returns true if valid (non-empty, at least 16 chars)
+ */
+export function isValidNodeSecret(nodeSecret: string): boolean {
+  return nodeSecret.length >= 16;
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Node Session Operations
+ *
+ * Wraps Rust node_auth module for Ed25519-based node authentication.
+ *
+ * ## Flow
+ * 1. ensureIdentity() - Create/load Ed25519 keypair (no auth required)
+ * 2. bootstrap({ startRunner: true }) - Register with engine + start runner
+ * 3. status() - Check current identity and session state
+ */
+
+import { OPS } from '../constants';
+import { _internal, makeRequest } from '../internal';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Node identity (public metadata - safe to log) */
+export interface NodeIdentity {
+  node_id: string;
+  public_key_b64: string;
+  private_key_vault_ref: string;
+  created_at: string;
+}
+
+/** Result from ensureIdentity */
+export interface EnsureIdentityResult {
+  ok: boolean;
+  node_id: string;
+  public_key_b64: string;
+  private_key_vault_ref: string;
+  created_at: string;
+}
+
+/** Options for bootstrap */
+export interface BootstrapOptions {
+  /** Start the runner after session is established (default: false) */
+  startRunner?: boolean;
+}
+
+/** Session info from bootstrap */
+export interface SessionInfo {
+  session_id: string;
+  tenant_id: string;
+  workspace_id: string;
+  expires_at: string;
+}
+
+/** Result from bootstrap */
+export interface BootstrapResult {
+  ok: boolean;
+  node_id: string;
+  public_key_b64: string;
+  registered: boolean;
+  session?: SessionInfo;
+}
+
+/** Node session status */
+export interface NodeSessionStatus {
+  hasIdentity: boolean;
+  hasSession: boolean;
+  sessionValid: boolean;
+  identity?: {
+    node_id: string;
+    public_key_b64: string;
+    created_at: string;
+  };
+  session?: {
+    session_id: string;
+    tenant_id: string;
+    workspace_id: string;
+    expires_at: string;
+    is_expired: boolean;
+  };
+}
+
+// =============================================================================
+// OPERATIONS
+// =============================================================================
+
+/**
+ * Ensure node identity exists (load or create keypair).
+ *
+ * Creates Ed25519 keypair if none exists.
+ * Does NOT require authentication.
+ *
+ * Call this during app startup before login.
+ */
+export async function ensureIdentity(): Promise<EnsureIdentityResult> {
+  const req = makeRequest(OPS.NODE_SESSION_ENSURE_IDENTITY, {});
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to ensure node identity');
+  }
+
+  return response.result as EnsureIdentityResult;
+}
+
+/**
+ * Bootstrap full node session.
+ *
+ * 1. Ensures identity exists
+ * 2. Registers node with engine (idempotent)
+ * 3. Gets challenge from engine
+ * 4. Signs challenge with Ed25519 private key
+ * 5. Exchanges signature for session token
+ * 6. Optionally starts the runner
+ *
+ * REQUIRES: User must be logged in (JWT required for registration).
+ */
+export async function bootstrap(options?: BootstrapOptions): Promise<BootstrapResult> {
+  const req = makeRequest(OPS.NODE_SESSION_BOOTSTRAP, {
+    startRunner: options?.startRunner ?? false,
+  });
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to bootstrap node session');
+  }
+
+  return response.result as BootstrapResult;
+}
+
+/**
+ * Get current node session status.
+ *
+ * Returns:
+ * - hasIdentity: Whether Ed25519 keypair exists
+ * - hasSession: Whether session token exists
+ * - sessionValid: Whether session is not expired
+ * - identity: Node identity metadata
+ * - session: Session metadata including expiry
+ */
+export async function status(): Promise<NodeSessionStatus> {
+  const req = makeRequest(OPS.NODE_SESSION_STATUS, {});
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to get node session status');
+  }
+
+  return response.result as NodeSessionStatus;
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Path Operations
+ *
+ * Wraps Rust handlers/paths.rs
+ */
+
+import { OPS } from '../constants';
+import { _internal, makeRequest } from '../internal';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type PathType =
+  | 'GENERAL'
+  | 'WORKSPACE'
+  | 'DATA'
+  | 'TEMP'
+  | 'CACHE'
+  | 'HOME';
+
+export type PathAccess = 'READ_ONLY' | 'READ_WRITE';
+
+export interface PathInfo {
+  path: string;
+  pathType: PathType;
+  access: PathAccess;
+  grantId: string;
+  expiresAt: string | null;
+  isValid: boolean;
+  /** Who issued the grant (e.g., "ekka-engine") */
+  issuer: string;
+  /** When the grant was issued (RFC3339) */
+  issuedAt: string;
+  /** User/subject who owns the grant */
+  subject: string;
+  /** Tenant ID */
+  tenantId: string;
+  /** Purpose of the grant */
+  purpose: string;
+}
+
+export interface PathCheckResult {
+  allowed: boolean;
+  reason: string;
+  pathType: PathType | null;
+  access: PathAccess | null;
+  /** The path prefix that granted access (use this for revoke) */
+  grantedBy: string | null;
+}
+
+export interface PathGrantResult {
+  success: boolean;
+  grantId: string | null;
+  expiresAt: string | null;
+  error: string | null;
+}
+
+export interface PathRequestOptions {
+  pathType?: PathType;
+  access?: PathAccess;
+}
+
+// =============================================================================
+// Raw Operations (Advanced API)
+// =============================================================================
+
+/**
+ * Check if an operation is allowed on a path.
+ * Maps to Rust: paths.check
+ */
+export async function check(
+  path: string,
+  operation: string = 'read'
+): Promise<PathCheckResult> {
+  const req = makeRequest(OPS.PATHS_CHECK, { path, operation });
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to check path');
+  }
+
+  return response.result as PathCheckResult;
+}
+
+/**
+ * List all path grants.
+ * Maps to Rust: paths.list
+ */
+export async function list(pathType?: PathType): Promise<PathInfo[]> {
+  const req = makeRequest(OPS.PATHS_LIST, { pathType });
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to list paths');
+  }
+
+  const result = response.result as { paths: PathInfo[] };
+  return result.paths;
+}
+
+/**
+ * Get information about a specific path.
+ * Maps to Rust: paths.get
+ */
+export async function get(path: string): Promise<PathInfo | null> {
+  const req = makeRequest(OPS.PATHS_GET, { path });
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to get path');
+  }
+
+  return response.result as PathInfo | null;
+}
+
+/**
+ * Request access to a path.
+ * Maps to Rust: paths.request
+ */
+export async function request(
+  path: string,
+  pathType: PathType = 'GENERAL',
+  access: PathAccess = 'READ_ONLY'
+): Promise<PathGrantResult> {
+  const req = makeRequest(OPS.PATHS_REQUEST, { path, pathType, access });
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to request path access');
+  }
+
+  return response.result as PathGrantResult;
+}
+
+/**
+ * Remove a path grant.
+ * Maps to Rust: paths.remove
+ */
+export async function remove(path: string): Promise<boolean> {
+  const req = makeRequest(OPS.PATHS_REMOVE, { path });
+  const response = await _internal.request(req);
+
+  if (!response.ok) {
+    throw new Error(response.error?.message || 'Failed to remove path');
+  }
+
+  const result = response.result as { removed: boolean };
+  return result.removed;
+}
+
+// =============================================================================
+// Simple Operations (Public API)
+// =============================================================================
+
+/**
+ * Check if an operation is allowed on a path.
+ * Simple boolean - no scary details.
+ */
+export async function isAllowed(
+  path: string,
+  operation: string = 'read'
+): Promise<boolean> {
+  try {
+    const result = await check(path, operation);
+    return result.allowed;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Allow access to a path.
+ * Simple wrapper for request with sensible defaults.
+ */
+export async function allow(
+  path: string,
+  options?: PathRequestOptions
+): Promise<PathGrantResult> {
+  const pathType = options?.pathType || 'WORKSPACE';
+  const access = options?.access || 'READ_WRITE';
+  return request(path, pathType, access);
+}