@falari/harness 0.0.0-stage → 0.8.9

package/lib/pin.js

@@ -0,0 +1,126 @@
+/**
+ * PIN-sealed storage for the Agent Key.
+ *
+ * The far_ export string is the only credential this plugin holds, and other
+ * plugins in the same profile can read the credentials store. So the string is
+ * never written in clear text: it is sealed with AES-256-GCM under a key derived
+ * from a PIN the user types (scrypt, 2^15 N), and the plaintext lives only in
+ * this process's memory while the panel is unlocked.
+ *
+ * The record shape is deliberately self-describing: a future KDF change can add
+ * a version without guessing what an older file used.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, scrypt as scryptCallback } from 'node:crypto';
+import { promisify } from 'node:util';
+
+const scrypt = promisify(scryptCallback);
+
+/** scrypt cost: about 100 ms per attempt on a laptop, which is the point. */
+const SCRYPT_N = 1 << 15;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const KEY_BYTES = 32;
+const SALT_BYTES = 16;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+/** A PIN nobody else can guess: six characters is the floor, not a target. */
+export const MIN_PIN_LENGTH = 6;
+export const SEALED_VERSION = 2;
+
+export class PinError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'PinError';
+    this.code = options.code || 'pin_error';
+    this.hint = options.hint;
+  }
+}
+
+/** Reject a PIN before it is used, so a mistake cannot become the only key. */
+export function validatePin(pin) {
+  const text = String(pin ?? '');
+  if (text.length < MIN_PIN_LENGTH) {
+    throw new PinError(`PIN must be at least ${MIN_PIN_LENGTH} characters.`, {
+      code: 'pin_too_short',
+      hint: 'Use at least six characters; a long phrase is stronger than four digits.',
+    });
+  }
+  if (text.length > 256) {
+    throw new PinError('PIN must be at most 256 characters.', { code: 'pin_too_long' });
+  }
+  if (!text.trim()) {
+    throw new PinError('PIN cannot be blank.', { code: 'pin_too_short' });
+  }
+  return text;
+}
+
+async function deriveKey(pin, salt, params) {
+  const buffer = await scrypt(String(pin).normalize('NFKC'), salt, KEY_BYTES, {
+    N: params.n,
+    r: params.r,
+    p: params.p,
+    maxmem: 256 * 1024 * 1024,
+  });
+  return buffer;
+}
+
+/** True when this record is a sealed secret rather than a legacy plaintext one. */
+export function isSealed(record) {
+  return Boolean(record && record.v === SEALED_VERSION && typeof record.ct === 'string');
+}
+
+/**
+ * Seal a secret under the PIN. Returns the record body to store: no plaintext,
+ * and everything needed to open it again with the same PIN.
+ */
+export async function sealSecret(secret, pin) {
+  const text = String(secret ?? '');
+  if (!text) throw new PinError('Nothing to seal.', { code: 'empty_secret' });
+  const normalized = validatePin(pin);
+  const salt = randomBytes(SALT_BYTES);
+  const iv = randomBytes(IV_BYTES);
+  const params = { n: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P };
+  const key = await deriveKey(normalized, salt, params);
+  const cipher = createCipheriv('aes-256-gcm', key, iv, { authTagLength: TAG_BYTES });
+  const ct = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    v: SEALED_VERSION,
+    kdf: 'scrypt',
+    n: params.n,
+    r: params.r,
+    p: params.p,
+    salt: salt.toString('base64'),
+    iv: iv.toString('base64'),
+    tag: tag.toString('base64'),
+    ct: ct.toString('base64'),
+  };
+}
+
+/**
+ * Open a sealed record. A wrong PIN and a tampered record are indistinguishable
+ * on purpose: GCM's tag fails for both, and saying which one it was would leak.
+ */
+export async function openSecret(record, pin) {
+  if (!isSealed(record)) throw new PinError('Record is not a sealed secret.', { code: 'not_sealed' });
+  const salt = Buffer.from(String(record.salt || ''), 'base64');
+  const iv = Buffer.from(String(record.iv || ''), 'base64');
+  const tag = Buffer.from(String(record.tag || ''), 'base64');
+  if (salt.length !== SALT_BYTES || iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+    throw new PinError('Sealed record is malformed.', { code: 'sealed_malformed' });
+  }
+  const params = { n: Number(record.n) || SCRYPT_N, r: Number(record.r) || SCRYPT_R, p: Number(record.p) || SCRYPT_P };
+  const key = await deriveKey(validatePin(pin), salt, params);
+  const decipher = createDecipheriv('aes-256-gcm', key, iv, { authTagLength: TAG_BYTES });
+  decipher.setAuthTag(tag);
+  try {
+    const plain = Buffer.concat([decipher.update(Buffer.from(String(record.ct || ''), 'base64')), decipher.final()]);
+    return plain.toString('utf8');
+  } catch {
+    throw new PinError('That PIN does not open this key.', {
+      code: 'wrong_pin',
+      hint: 'The PIN is not recoverable: without it the stored key cannot be read, and the wallet export must be entered again.',
+    });
+  }
+}

package/lib/routes.js

@@ -0,0 +1,311 @@
+/**
+ * Browser routes for the Web panel and settings page.
+ *
+ * The panel runs in the same origin as Host, so every write is checked against
+ * the Host header and the response never carries CORS headers. Nothing here
+ * returns the Agent Key.
+ */
+import { publicError, ServiceError } from './errors.js';
+
+const MAX_JSON_BODY = 64 * 1024;
+
+function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+function sendError(res, error) {
+  sendJson(res, statusFor(error), { ok: false, error: publicError(error) });
+}
+
+export function statusFor(error) {
+  const code = error && typeof error.code === 'string' ? error.code : '';
+  if (code === 'payload_too_large' || code === 'file_too_large') return 413;
+  if (code === 'not_found' || code === 'task_not_found' || code === 'source_missing') return 404;
+  if (code === 'method_not_allowed' || code === 'unsupported_action') return 405;
+  if (code === 'budget_shortfall' || code === 'no_agent_key' || code === 'permission_missing') return 409;
+  // Lock state is a precondition, not a bad request: 423 keeps it distinct from
+  // a real validation failure, and 401 is reserved for a wrong PIN.
+  if (code === 'agent_key_locked' || code === 'pin_required' || code === 'no_sealed_key' || code === 'upload_in_progress') return 423;
+  if (code === 'wrong_pin') return 401;
+  if (code === 'pin_blocked') return 429;
+  if (code === 'data_key_missing' || code === 'path_outside_download_dir' || code === 'path_outside_workspace') return 400;
+  return 400;
+}
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+/**
+ * The panel talks to the Host over loopback. Refusing other peers keeps the
+ * key-changing and paid-upload routes away from a listener that a composition
+ * may have bound to a wider address; a relay that proxies to localhost still
+ * arrives from a loopback address.
+ */
+function isLoopback(req) {
+  const address = req.socket && req.socket.remoteAddress;
+  if (!address) return true;
+  return LOOPBACK.has(address) || address.startsWith('127.');
+}
+
+function isSameOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  try {
+    return new URL(origin).host === req.headers.host;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonBody(req, limit = MAX_JSON_BODY) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > limit) throw new ServiceError('payload_too_large', `Request body exceeds ${limit} bytes.`);
+    chunks.push(chunk);
+  }
+  if (size === 0) return {};
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch {
+    throw new ServiceError('invalid_json', 'Request body is not valid JSON.');
+  }
+}
+
+function methodNotAllowed(res, allowed) {
+  sendJson(res, 405, { ok: false, error: { code: 'method_not_allowed', message: `${allowed} only.` } });
+}
+
+export function registerRoutes(ctx, service, config, prefix) {
+  const webServer = ctx.get('webServer');
+  if (!webServer || typeof webServer.register !== 'function') {
+    ctx.logger?.debug?.('falari-harness: webServer unavailable; settings API not mounted');
+    return;
+  }
+
+  const dispose = webServer.register({
+    kind: 'prefix',
+    path: prefix,
+    handler: async (req, res) => {
+      if (!config.allowRemoteRoutes && !isLoopback(req)) {
+        sendJson(res, 403, { ok: false, error: { code: 'remote_forbidden', message: 'Falari Harness routes are local-only.' } });
+        return;
+      }
+      if (!isSameOrigin(req)) {
+        sendJson(res, 403, { ok: false, error: { code: 'cross_origin', message: 'Cross-origin requests are not allowed.' } });
+        return;
+      }
+      const url = new URL(req.url || prefix, 'http://localhost');
+      const full = url.pathname;
+      const path = full.startsWith(prefix) ? full.slice(prefix.length) || '/' : full;
+      const parts = path.split('/').filter(Boolean);
+      try {
+        await dispatch(req, res, url, parts);
+      } catch (error) {
+        sendError(res, error);
+      }
+    },
+  });
+  ctx.effect(() => dispose, 'falari-harness: routes');
+
+  async function dispatch(req, res, url, parts) {
+    // /status and /health
+    if (parts.length === 1 && parts[0] === 'status') {
+      if (req.method !== 'GET') return methodNotAllowed(res, 'GET');
+      const refresh = url.searchParams.get('refresh') === '1';
+      return sendJson(res, 200, { ok: true, value: await service.keyStatus({ refresh }) });
+    }
+    if (parts.length === 1 && parts[0] === 'health') {
+      const security = await service.securityView();
+      return sendJson(res, 200, {
+        ok: true,
+        value: {
+          service: 'falari-harness',
+          configured: security.mode !== 'none',
+          encrypted: security.mode === 'sealed',
+          locked: security.locked,
+          network: config.network,
+        },
+      });
+    }
+    if (parts.length === 1 && parts[0] === 'config') {
+      if (req.method === 'GET') {
+        return sendJson(res, 200, {
+          ok: true,
+          value: {
+            network: config.network,
+            defaultPrivacy: config.defaultPrivacy,
+            defaultDuration: config.defaultDuration,
+            maxFileSizeBytes: config.maxFileSizeBytes,
+            lockIdleMinutes: config.lockIdleMinutes,
+            allowUploadOutsideWorkspace: config.allowUploadOutsideWorkspace,
+            allowRemoteRoutes: config.allowRemoteRoutes,
+            downloadDir: config.downloadDir || service.downloadDir,
+            gatewayUrl: config.gatewayUrl || '',
+            retrievalUrl: config.retrievalUrl || '',
+            explorerUrl: config.explorerUrl || '',
+            timeoutMs: config.timeoutMs,
+          },
+        });
+      }
+      if (req.method === 'POST') {
+        const body = await readJsonBody(req);
+        return sendJson(res, 200, { ok: true, value: await service.updateConfig(body) });
+      }
+      return methodNotAllowed(res, 'GET or POST');
+    }
+
+    // /key
+    if (parts.length === 1 && parts[0] === 'key') {
+      if (req.method === 'GET') {
+        return sendJson(res, 200, { ok: true, value: await service.keyStatus({ refresh: url.searchParams.get('refresh') === '1' }) });
+      }
+      if (req.method === 'DELETE') return sendJson(res, 200, { ok: true, value: await service.clearKey() });
+      if (req.method !== 'POST') return methodNotAllowed(res, 'GET, POST or DELETE');
+      const body = await readJsonBody(req);
+      const key = typeof body.key === 'string' ? body.key : '';
+      const pin = typeof body.pin === 'string' ? body.pin : '';
+      if (!key.trim()) throw new ServiceError('missing_key', 'Paste the far_ Agent Key first.');
+      if (!pin.trim()) {
+        throw new ServiceError(
+          'missing_pin',
+          'A PIN is required: the key is stored encrypted, never in clear text.',
+          'Pick a PIN of at least six characters. It is the only thing that can open the stored key.',
+        );
+      }
+      return sendJson(res, 200, { ok: true, value: await service.configureKey(key, pin) });
+    }
+
+    // /key/unlock and /key/lock move the plaintext between the PIN and memory.
+    if (parts.length === 2 && parts[0] === 'key' && parts[1] === 'unlock') {
+      if (req.method !== 'POST') return methodNotAllowed(res, 'POST');
+      const body = await readJsonBody(req);
+      const pin = typeof body.pin === 'string' ? body.pin : '';
+      if (!pin) throw new ServiceError('missing_pin', 'Enter the PIN that protects this key.');
+      return sendJson(res, 200, { ok: true, value: await service.unlock(pin) });
+    }
+    if (parts.length === 2 && parts[0] === 'key' && parts[1] === 'lock') {
+      if (req.method !== 'POST') return methodNotAllowed(res, 'POST');
+      const body = await readJsonBody(req);
+      // Locking mid-upload stops the queue and strands a paid task, so it takes
+      // an explicit force; the panel offers it only when the user insists.
+      if (!body.force && (await service.hasActiveUploads())) {
+        throw new ServiceError(
+          'upload_in_progress',
+          'An upload is still running. Locking now would pause it until the PIN is entered again.',
+          'Wait for the upload to finish, or send force:true to lock anyway.',
+        );
+      }
+      const locked = service.lock('panel');
+      return sendJson(res, 200, { ok: true, value: { locked, security: await service.securityView() } });
+    }
+    if (parts.length === 2 && parts[0] === 'key' && parts[1] === 'secure') {
+      if (req.method !== 'POST') return methodNotAllowed(res, 'POST');
+      const body = await readJsonBody(req);
+      const pin = typeof body.pin === 'string' ? body.pin : '';
+      if (!pin) throw new ServiceError('missing_pin', 'Set a PIN to encrypt the stored key.');
+      return sendJson(res, 200, { ok: true, value: await service.secureLegacyKey(pin) });
+    }
+    if (parts.length === 2 && parts[0] === 'key' && parts[1] === 'security') {
+      if (req.method !== 'GET') return methodNotAllowed(res, 'GET');
+      return sendJson(res, 200, { ok: true, value: await service.securityView() });
+    }
+
+    // /quote
+    if (parts.length === 1 && parts[0] === 'quote') {
+      if (req.method !== 'POST') return methodNotAllowed(res, 'POST');
+      const body = await readJsonBody(req);
+      return sendJson(res, 200, {
+        ok: true,
+        value: await service.quote({ sizeBytes: Number(body.sizeBytes), duration: body.duration }),
+      });
+    }
+
+    // /uploads — raw octet-stream body, one file per request
+    if (parts.length === 1 && parts[0] === 'uploads') {
+      if (req.method !== 'POST') return methodNotAllowed(res, 'POST');
+      const declared = Number(req.headers['content-length'] ?? 0);
+      if (Number.isFinite(declared) && declared > config.maxFileSizeBytes) {
+        throw new ServiceError(
+          'file_too_large',
+          `The file is above the configured limit of ${config.maxFileSizeBytes} bytes.`,
+          'Raise maxFileSizeBytes in the plugin configuration to allow larger uploads.',
+        );
+      }
+      const task = await service.saveUploadStream(req, {
+        fileName: url.searchParams.get('fileName') || '',
+        privacy: url.searchParams.get('privacy') || undefined,
+        duration: url.searchParams.get('duration') || undefined,
+      });
+      return sendJson(res, 202, { ok: true, value: task });
+    }
+
+    // /intents and /intents/:id
+    if (parts.length >= 1 && parts[0] === 'intents') {
+      if (req.method !== 'GET') return methodNotAllowed(res, 'GET');
+      if (parts.length === 1) {
+        const limit = Number(url.searchParams.get('limit') ?? 50);
+        return sendJson(res, 200, { ok: true, value: await service.listIntents({ limit }) });
+      }
+      if (parts.length === 2) {
+        return sendJson(res, 200, { ok: true, value: await service.getIntent(decodeURIComponent(parts[1])) });
+      }
+      throw new ServiceError('not_found', 'Unknown Falari Harness route.');
+    }
+
+    // /downloads — POST starts a task, GET /downloads/:id reads it
+    if (parts.length >= 1 && parts[0] === 'downloads') {
+      if (parts.length === 1) {
+        if (req.method !== 'POST') return methodNotAllowed(res, 'POST');
+        const body = await readJsonBody(req);
+        return sendJson(res, 202, {
+          ok: true,
+          value: await service.startDownload({
+            intentId: body.intentId,
+            dataKey: typeof body.dataKey === 'string' ? body.dataKey : undefined,
+            outPath: typeof body.outPath === 'string' ? body.outPath : undefined,
+          }),
+        });
+      }
+      if (parts.length === 2 && req.method === 'GET') {
+        return sendJson(res, 200, { ok: true, value: await service.getTask(decodeURIComponent(parts[1])) });
+      }
+      throw new ServiceError('not_found', 'Unknown Falari Harness route.');
+    }
+
+    // /tasks and /tasks/:id[/action]
+    if (parts.length >= 1 && parts[0] === 'tasks') {
+      if (parts.length === 1) {
+        if (req.method !== 'GET') return methodNotAllowed(res, 'GET');
+        return sendJson(res, 200, { ok: true, value: await service.listTasks() });
+      }
+      const id = decodeURIComponent(parts[1]);
+      if (parts.length === 2) {
+        if (req.method !== 'GET') return methodNotAllowed(res, 'GET');
+        return sendJson(res, 200, { ok: true, value: await service.getTask(id) });
+      }
+      // /tasks/:id/refund previews the escrow maths; /tasks/:id/cancel performs
+      // the termination and answers with what the chain actually released.
+      if (parts.length === 3 && parts[2] === 'refund') {
+        if (req.method !== 'GET') return methodNotAllowed(res, 'GET');
+        return sendJson(res, 200, { ok: true, value: await service.refundPreview(id) });
+      }
+      if (parts.length === 3 && parts[2] === 'cancel') {
+        if (req.method !== 'POST') return methodNotAllowed(res, 'POST');
+        return sendJson(res, 200, { ok: true, value: await service.cancelUpload(id) });
+      }
+      if (parts.length === 3 && req.method === 'POST') {
+        return sendJson(res, 200, { ok: true, value: await service.taskAction(id, parts[2]) });
+      }
+      throw new ServiceError('not_found', 'Unknown Falari Harness route.');
+    }
+
+    throw new ServiceError('not_found', 'Unknown Falari Harness route.');
+  }
+}

package/lib/sdk.js

@@ -0,0 +1,13 @@
+/**
+ * The bundled Falari Agent SDK (@falari/agent + @falari/precompiles).
+ *
+ * Both packages are not published to npm, so `scripts/build-sdk.sh` bundles
+ * them into `lib/falari-sdk.cjs`; this module is the single place that loads
+ * that bundle so every Host module shares one instance.
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const sdk = require('./falari-sdk.cjs');
+export const { FalariAgent, FalariError, ApiError } = sdk;