@falari/harness 0.0.0-stage → 0.8.10

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Bundle patch layer: the row loads the package's main entry as the Host half
+# (a plain Cordis plugin); the `dsh.client` declaration makes the Web app load
+# its ./client bundle as the browser half.
+- insert:
+    - id: falari-harness
+      name: '@falari/harness'

package/index.js

@@ -0,0 +1,52 @@
+/**
+ * Host half of the Falari Harness bundle.
+ *
+ * M2 scope: Agent Key status, upload quotes, the SDK-backed upload queue and
+ * its panel routes. Downloads arrive in M3.
+ */
+import { resolveConfig } from './lib/config.js';
+import { registerRoutes } from './lib/routes.js';
+import { FalariDataService } from './lib/service.js';
+import { registerTools } from './lib/tools.js';
+
+const API_PREFIX = '/api/falari-harness';
+
+export const inject = ['tools', 'credentials'];
+
+export function apply(ctx, config) {
+  const resolved = resolveConfig(config);
+  const service = new FalariDataService(ctx, resolved, ctx.credentials);
+
+  ctx.effect(() => () => service.dispose(), 'falari-harness: service');
+  ctx.effect(() => {
+    service.start().catch((error) => {
+      ctx.logger?.warn?.(`falari-harness: startup failed: ${error && error.message ? error.message : error}`);
+    });
+    return () => {};
+  }, 'falari-harness: startup');
+
+  // Tell the Settings service that this plugin ships its own configuration
+  // page, so no schema-generated form is offered for it. Optional: profiles
+  // without the Settings service keep the business plugin working.
+  if (typeof ctx.inject === 'function') {
+    try {
+      ctx.inject(['settings'], (child) => {
+        const settings = child.settings;
+        if (!settings || typeof settings.configure !== 'function') return;
+        child.effect(() => {
+          try {
+            return settings.configure({ auto: false }, ctx.fiber);
+          } catch {
+            return undefined;
+          }
+        }, 'falari-harness: own config page');
+      });
+    } catch (error) {
+      ctx.logger?.debug?.(`falari-harness: settings policy skipped: ${error && error.message ? error.message : error}`);
+    }
+  }
+
+  registerTools(ctx, service);
+  registerRoutes(ctx, service, resolved, API_PREFIX);
+  ctx.logger?.debug?.(`falari-harness: host ready on ${resolved.network}`);
+}

package/lib/config.js

@@ -0,0 +1,103 @@
+/** Plugin configuration resolution. Secrets never live here — see lib/service.js. */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const DEFAULT_TIMEOUT_MS = 60_000;
+export const DEFAULT_MAX_FILE_SIZE = 2 * 1024 ** 3;
+const DEFAULT_LOCK_IDLE_MINUTES = 60;
+export const DEFAULT_DURATION = 'permanent';
+
+export const DURATION_NAMES = ['permanent', '30d', '90d', '1y', '5y', '10y'];
+
+export function defaultDataDir() {
+  const profile = process.env.DSH_PROFILE_DIR;
+  return join(profile || join(homedir(), '.dsh', 'profiles', 'desktop'), 'falari-harness');
+}
+
+function text(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function nonNegativeNumber(value, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0) return fallback;
+  return Math.trunc(number);
+}
+
+function positiveNumber(value, fallback) {
+  return Number.isFinite(value) && value > 0 ? Math.trunc(value) : fallback;
+}
+
+const NETWORKS = ['testnet', 'mainnet'];
+const PRIVACIES = ['public', 'private'];
+
+/**
+ * Validate an edit coming from the settings page. Only fields the panel owns are
+ * accepted; unknown keys are refused instead of silently dropped.
+ */
+export function validateConfigPatch(patch) {
+  const input = patch && typeof patch === 'object' ? patch : {};
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (key === 'network') {
+      if (!NETWORKS.includes(value)) throw new Error('network must be testnet or mainnet');
+      out.network = value;
+    } else if (key === 'defaultPrivacy') {
+      if (!PRIVACIES.includes(value)) throw new Error('defaultPrivacy must be public or private');
+      out.defaultPrivacy = value;
+    } else if (key === 'defaultDuration') {
+      if (!DURATION_NAMES.includes(value)) throw new Error(`defaultDuration must be one of ${DURATION_NAMES.join(', ')}`);
+      out.defaultDuration = value;
+    } else if (key === 'maxFileSizeBytes') {
+      const size = Number(value);
+      if (!Number.isSafeInteger(size) || size < 1024) throw new Error('maxFileSizeBytes must be an integer of at least 1024');
+      out.maxFileSizeBytes = size;
+    } else if (key === 'lockIdleMinutes') {
+      const minutes = Number(value);
+      if (!Number.isInteger(minutes) || minutes < 0 || minutes > 7 * 24 * 60) {
+        throw new Error('lockIdleMinutes must be an integer between 0 and 10080 (7 days)');
+      }
+      out.lockIdleMinutes = minutes;
+    } else if (key === 'timeoutMs') {
+      const ms = Number(value);
+      if (!Number.isSafeInteger(ms) || ms < 1000 || ms > 600000) throw new Error('timeoutMs must be between 1000 and 600000');
+      out.timeoutMs = ms;
+    } else if (key === 'downloadDir') {
+      if (value === null || value === '') out.downloadDir = '';
+      else if (typeof value === 'string' && value.startsWith('/')) out.downloadDir = value.trim();
+      else throw new Error('downloadDir must be an absolute path or empty');
+    } else if (key === 'gatewayUrl' || key === 'retrievalUrl' || key === 'explorerUrl') {
+      if (value === null || value === '') out[key] = '';
+      else if (typeof value === 'string' && /^https?:\/\//.test(value)) out[key] = value.trim();
+      else throw new Error(`${key} must be an http(s) URL or empty`);
+    } else if (key === 'allowUploadOutsideWorkspace' || key === 'allowRemoteRoutes') {
+      if (typeof value !== 'boolean') throw new Error(`${key} must be a boolean`);
+      out[key] = value;
+    } else {
+      throw new Error(`unsupported configuration field: ${key}`);
+    }
+  }
+  return out;
+}
+
+export function resolveConfig(input) {
+  const config = input && typeof input === 'object' ? input : {};
+  const privacy = config.defaultPrivacy === 'private' ? 'private' : 'public';
+  const duration = DURATION_NAMES.includes(config.defaultDuration) ? config.defaultDuration : DEFAULT_DURATION;
+  return {
+    network: config.network === 'mainnet' ? 'mainnet' : 'testnet',
+    gatewayUrl: text(config.gatewayUrl),
+    retrievalUrl: text(config.retrievalUrl),
+    explorerUrl: text(config.explorerUrl),
+    timeoutMs: positiveNumber(config.timeoutMs, DEFAULT_TIMEOUT_MS),
+    dataDir: text(config.dataDir) || defaultDataDir(),
+    downloadDir: text(config.downloadDir),
+    defaultPrivacy: privacy,
+    defaultDuration: duration,
+    maxFileSizeBytes: positiveNumber(config.maxFileSizeBytes, DEFAULT_MAX_FILE_SIZE),
+    // Minutes an unlocked Agent Key stays in memory; 0 keeps it until lock/exit.
+    lockIdleMinutes: nonNegativeNumber(config.lockIdleMinutes, DEFAULT_LOCK_IDLE_MINUTES),
+    allowUploadOutsideWorkspace: config.allowUploadOutsideWorkspace === true,
+    allowRemoteRoutes: config.allowRemoteRoutes === true,
+  };
+}

package/lib/errors.js

@@ -0,0 +1,40 @@
+/** Error shape shared by the tools and the HTTP routes. */
+import { sdk } from './sdk.js';
+
+export class ServiceError extends Error {
+  constructor(code, message, hint = '') {
+    super(message);
+    this.name = 'ServiceError';
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+export function errorText(error) {
+  const message = error && typeof error.message === 'string' ? error.message : String(error);
+  return message.trim() || 'unknown error';
+}
+
+export function publicError(error) {
+  if (error instanceof ServiceError) {
+    return { code: error.code, message: error.message, hint: error.hint || undefined };
+  }
+  if (sdk.FalariError && error instanceof sdk.FalariError) {
+    return { code: error.code || 'falari_error', message: error.message, hint: error.hint || undefined };
+  }
+  if (sdk.ApiError && error instanceof sdk.ApiError) {
+    if (error.status === 404 && /account .* does not exist/i.test(error.message)) {
+      return {
+        code: 'master_account_not_found',
+        message: error.message,
+        hint: 'The key belongs to a master account that does not exist on this network. Check the network and the wallet that exported the key.',
+      };
+    }
+    return {
+      code: error.code || (error.status === 404 ? 'not_found' : 'gateway_error'),
+      message: error.message,
+      hint: error.status === 401 || error.status === 403 ? 'The gateway rejected this request.' : undefined,
+    };
+  }
+  return { code: 'internal_error', message: errorText(error) };
+}