farming-code 2.2.8 → 2.2.12

package/backend/control-api.js

@@ -1,6 +1,8 @@
 const express = require('express');
+const { runtimeKind } = require('./agent-runtime-binding');
+const { terminalInputReady } = require('./terminal-status');
 
-const DEFAULT_INITIAL_INPUT_DELAY_MS = 2500;
+const DEFAULT_INITIAL_INPUT_TIMEOUT_MS = 30000;
 
 function ensureTrailingNewline(value) {
   const text = String(value || '');
@@ -17,12 +19,103 @@ function normalizeTail(value, fallback = 4000) {
   return Math.max(0, Math.min(100000, Math.floor(tail)));
 }
 
+function terminalReadinessOptions(agent) {
+  return {
+    command: agent.command,
+    cwd: agent.terminalStatus?.cwd || agent.cwd,
+    status: agent.status === 'running' ? 'running' : agent.status,
+    title: agent.terminalStatus?.title || agent.sessionTitle || '',
+    previewText: agent.previewText || '',
+    terminalBusy: typeof agent.terminalBusy === 'boolean' ? agent.terminalBusy : null,
+    shellLastEvent: agent.terminalStatus?.source === 'shell-status-marker' ? 'finish' : '',
+    shellLastExitCode: agent.terminalStatus?.lastExitCode,
+    shellCommand: agent.terminalStatus?.runningCommand || '',
+  };
+}
+
+function waitForTerminalInputReadiness(agentManager, agentId, options = {}) {
+  const expectedStartedAt = Number(options.expectedStartedAt);
+  const initialRuntimeEpoch = typeof options.expectedRuntimeEpoch === 'string'
+    ? options.expectedRuntimeEpoch
+    : '';
+  const timeoutMs = Number.isFinite(options.timeoutMs)
+    ? Math.max(1, options.timeoutMs)
+    : DEFAULT_INITIAL_INPUT_TIMEOUT_MS;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let expectedRuntimeEpoch = initialRuntimeEpoch;
+    const removeUpdateListener = () => {
+      if (typeof agentManager.off === 'function') agentManager.off('update', inspect);
+      else if (typeof agentManager.removeListener === 'function') agentManager.removeListener('update', inspect);
+    };
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      removeUpdateListener();
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const fail = (code, message) => {
+      const error = new Error(message);
+      error.code = code;
+      finish(error);
+    };
+    const inspect = () => {
+      const agent = findAgent(agentManager.getState(), agentId);
+      if (!agent) {
+        fail('agent-removed', 'Agent disappeared before its initial Terminal task was delivered');
+        return;
+      }
+      if (Number(agent.startedAt) !== expectedStartedAt) {
+        fail('runtime-replaced', 'Agent runtime was replaced before its initial Terminal task was delivered');
+        return;
+      }
+      if (agent.terminalInputReceived === true) {
+        fail('terminal-already-used', 'Terminal received user input before its initial task was delivered');
+        return;
+      }
+      if (agent.status === 'dead' || agent.status === 'stopped') {
+        fail('runtime-exited', 'Agent exited before its initial Terminal task was delivered');
+        return;
+      }
+      const runtimeEpoch = typeof agent.runtimeEpoch === 'string' ? agent.runtimeEpoch : '';
+      if (!runtimeEpoch) return;
+      if (expectedRuntimeEpoch && runtimeEpoch !== expectedRuntimeEpoch) {
+        fail('runtime-replaced', 'Agent runtime changed before its initial Terminal task was delivered');
+        return;
+      }
+      expectedRuntimeEpoch = runtimeEpoch;
+      if (agent.status !== 'running' || !terminalInputReady(terminalReadinessOptions(agent))) return;
+      finish(null, {
+        expectedStartedAt,
+        expectedRuntimeEpoch,
+      });
+    };
+    const timeout = setTimeout(() => {
+      fail('initial-input-timeout', 'Terminal did not become ready for its initial task before the timeout');
+    }, timeoutMs);
+    timeout.unref?.();
+    if (typeof agentManager.on === 'function') agentManager.on('update', inspect);
+    Promise.resolve().then(inspect);
+  });
+}
+
 function createControlRouter(agentManager, options = {}) {
   const router = express.Router();
   const notifyUpdate = typeof options.notifyUpdate === 'function' ? options.notifyUpdate : () => {};
-  const initialInputDelayMs = Number.isFinite(options.initialInputDelayMs)
-    ? Math.max(0, options.initialInputDelayMs)
-    : DEFAULT_INITIAL_INPUT_DELAY_MS;
+  const initialInputTimeoutMs = Number.isFinite(options.initialInputTimeoutMs)
+    ? Math.max(1, options.initialInputTimeoutMs)
+    : DEFAULT_INITIAL_INPUT_TIMEOUT_MS;
+
+  async function runTerminalMutation(agentId, expectedRuntimeEpoch, operation) {
+    const current = findAgent(agentManager.getState(), agentId);
+    if (!current || current.runtimeEpoch !== expectedRuntimeEpoch) {
+      return { status: 'rejected', reason: 'runtime-epoch-mismatch' };
+    }
+    return operation({ expectedRuntimeEpoch });
+  }
 
   router.use(express.json({ limit: '1mb' }));
 
@@ -62,17 +155,64 @@ function createControlRouter(agentManager, options = {}) {
         return;
       }
 
-      if (initialInput) {
-        setTimeout(() => {
-          if (!findAgent(agentManager.getState(), agentId)) return;
-          agentManager.sendInput(agentId, ensureTrailingNewline(initialInput)).catch(() => {});
-        }, initialInputDelayMs);
-      }
+      void (async () => {
+        if (!initialInput) {
+          notifyUpdate();
+          res.status(201).json({ agentId, initialInputDelivered: false });
+          return;
+        }
 
-      notifyUpdate();
-      res.status(201).json({
-        agentId,
-        scheduledInitialInput: Boolean(initialInput),
+        const started = findAgent(agentManager.getState(), agentId);
+        if (!started) throw Object.assign(new Error('Agent disappeared before initial input delivery'), {
+          code: 'agent-removed',
+        });
+        const structuredRuntime = runtimeKind(started) !== 'terminal';
+        if (structuredRuntime) {
+          await agentManager.sendComposerMessage(agentId, initialInput);
+          notifyUpdate();
+          res.status(201).json({ agentId, initialInputDelivered: true, inputMode: 'structured' });
+          return;
+        }
+
+        const readiness = await waitForTerminalInputReadiness(agentManager, agentId, {
+          expectedStartedAt: started.startedAt,
+          expectedRuntimeEpoch: started.runtimeEpoch,
+          timeoutMs: initialInputTimeoutMs,
+        });
+        const result = await runTerminalMutation(
+          agentId,
+          readiness.expectedRuntimeEpoch,
+          async ({ expectedRuntimeEpoch }) => {
+            const current = findAgent(agentManager.getState(), agentId);
+            if (
+              !current ||
+              Number(current.startedAt) !== readiness.expectedStartedAt ||
+              current.runtimeEpoch !== readiness.expectedRuntimeEpoch ||
+              current.terminalInputReceived === true ||
+              current.status !== 'running' ||
+              !terminalInputReady(terminalReadinessOptions(current))
+            ) {
+              return { status: 'rejected', reason: 'startup-state-changed' };
+            }
+            return agentManager.sendInput(agentId, ensureTrailingNewline(initialInput), {
+              expectedRuntimeEpoch,
+            });
+          },
+        );
+        if (!result || result.status === 'rejected' || result.status === 'input-rejected') {
+          const reason = result?.reason || 'initial-input-rejected';
+          throw Object.assign(new Error(`Initial Terminal task was not delivered: ${reason}`), { code: reason });
+        }
+        notifyUpdate();
+        res.status(201).json({ agentId, initialInputDelivered: true, inputMode: 'terminal' });
+      })().catch((deliveryError) => {
+        const status = deliveryError?.code === 'initial-input-timeout' ? 504 : 409;
+        res.status(status).json({
+          error: deliveryError?.message || 'Initial input delivery failed',
+          code: deliveryError?.code || 'initial-input-failed',
+          agentId,
+          initialInputDelivered: false,
+        });
       });
     }, {
       wantsMain: false,
@@ -94,9 +234,25 @@ function createControlRouter(agentManager, options = {}) {
       return;
     }
 
+    if (agentManager.agentSupportsTerminalInput?.(agentId) === false) {
+      res.status(409).json({ error: 'raw input is only available for Terminal Agents' });
+      return;
+    }
+    const expectedRuntimeEpoch = typeof findAgent(agentManager.getState(), agentId)?.runtimeEpoch === 'string'
+      ? findAgent(agentManager.getState(), agentId).runtimeEpoch
+      : '';
+    if (!expectedRuntimeEpoch) {
+      res.status(409).json({ error: 'terminal runtime is not ready' });
+      return;
+    }
     const input = typeof req.body.input === 'string' ? req.body.input : '';
-    await agentManager.sendInput(agentId, input);
-    notifyUpdate();
+    const result = await runTerminalMutation(agentId, expectedRuntimeEpoch, ({ expectedRuntimeEpoch: epoch }) => (
+      agentManager.sendInput(agentId, input, { expectedRuntimeEpoch: epoch })
+    ));
+    if (!result || result.status === 'rejected' || result.status === 'input-rejected') {
+      res.status(409).json({ error: result?.reason || 'terminal input rejected' });
+      return;
+    }
     res.json({ success: true });
   });
 
@@ -108,7 +264,24 @@ function createControlRouter(agentManager, options = {}) {
       return;
     }
 
-    const result = await agentManager.clearAgentSessionBuffer(agentId);
+    if (agentManager.agentSupportsTerminalInput?.(agentId) === false) {
+      res.status(409).json({ error: 'clear is only available for Terminal Agents' });
+      return;
+    }
+    const expectedRuntimeEpoch = typeof findAgent(agentManager.getState(), agentId)?.runtimeEpoch === 'string'
+      ? findAgent(agentManager.getState(), agentId).runtimeEpoch
+      : '';
+    if (!expectedRuntimeEpoch) {
+      res.status(409).json({ error: 'terminal runtime is not ready' });
+      return;
+    }
+    const result = await runTerminalMutation(agentId, expectedRuntimeEpoch, ({ expectedRuntimeEpoch: epoch }) => (
+      agentManager.clearAgentSessionBuffer(agentId, { expectedRuntimeEpoch: epoch })
+    ));
+    if (!result || result.status === 'rejected' || result.cleared === false) {
+      res.status(409).json({ error: result?.reason || result?.error || 'terminal clear rejected' });
+      return;
+    }
     notifyUpdate();
     res.json({ success: Boolean(result && result.cleared), ...result });
   });
@@ -146,6 +319,8 @@ function createControlRouter(agentManager, options = {}) {
 }
 
 module.exports = {
+  DEFAULT_INITIAL_INPUT_TIMEOUT_MS,
   createControlRouter,
   ensureTrailingNewline,
+  waitForTerminalInputReadiness,
 };

package/backend/executable-discovery.js

@@ -4,6 +4,7 @@ const { execFileSync } = require('child_process');
 const { getUserLaunchAgents } = require('./cli-agents');
 
 const DEFAULT_CODEX_APP_BIN = '/Applications/Codex.app/Contents/Resources/codex';
+const DEFAULT_CHATGPT_APP_CODEX_BIN = '/Applications/ChatGPT.app/Contents/Resources/codex';
 const executableVersionCache = new Map();
 
 function getPathDirectories(pathEnv = process.env.PATH || '') {
@@ -90,6 +91,7 @@ function getPreferredExecutableCandidates(agentName, pathEnv = process.env.PATH
   return [
     process.env.FARMING_CODEX_BIN || '',
     DEFAULT_CODEX_APP_BIN,
+    DEFAULT_CHATGPT_APP_CODEX_BIN,
     ...pathCandidates,
   ].filter(Boolean);
 }

package/backend/farming-net-pass.js

@@ -0,0 +1,285 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const PASS_QUERY_PARAM = 'farming_net_pass';
+const PASS_SCOPE = 'farming:open';
+const DEFAULT_PASS_TTL_SECONDS = 30;
+const MAX_PASS_TTL_SECONDS = 60;
+const CLOCK_SKEW_SECONDS = 5;
+
+function normalizeAudience(value) {
+  const audience = String(value || '').trim().toLowerCase();
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(audience)) {
+    throw new Error('Invalid Farming Net audience');
+  }
+  return audience;
+}
+
+function normalizeIssuerId(value) {
+  const issuerId = String(value || '').trim();
+  if (!/^[A-Za-z0-9_-]{8,80}$/.test(issuerId)) {
+    throw new Error('Invalid Farming Net issuer id');
+  }
+  return issuerId;
+}
+
+function normalizeSubject(value) {
+  const subject = String(value || 'owner').trim();
+  if (!subject || subject.length > 80 || /[\x00-\x1f\x7f]/.test(subject)) {
+    throw new Error('Invalid Farming Net subject');
+  }
+  return subject;
+}
+
+function safeTtlSeconds(value) {
+  const ttl = Number(value);
+  if (!Number.isInteger(ttl)) return DEFAULT_PASS_TTL_SECONDS;
+  return Math.min(MAX_PASS_TTL_SECONDS, Math.max(5, ttl));
+}
+
+function publicKeyDetails(publicKeyPem) {
+  const publicKey = publicKeyPem && typeof publicKeyPem === 'object' && publicKeyPem.type === 'public'
+    ? publicKeyPem
+    : crypto.createPublicKey(String(publicKeyPem || ''));
+  if (publicKey.asymmetricKeyType !== 'ed25519') {
+    throw new Error('Farming Net requires an Ed25519 public key');
+  }
+  const canonicalPem = publicKey.export({ format: 'pem', type: 'spki' }).toString();
+  const der = publicKey.export({ format: 'der', type: 'spki' });
+  const issuer = `fnet_${crypto.createHash('sha256').update(der).digest('base64url').slice(0, 24)}`;
+  return { canonicalPem, issuer, publicKey };
+}
+
+function privateKeyDetails(privateKeyPem) {
+  const privateKey = crypto.createPrivateKey(String(privateKeyPem || ''));
+  if (privateKey.asymmetricKeyType !== 'ed25519') {
+    throw new Error('Farming Net requires an Ed25519 private key');
+  }
+  const canonicalPem = privateKey.export({ format: 'pem', type: 'pkcs8' }).toString();
+  const publicDetails = publicKeyDetails(crypto.createPublicKey(privateKey));
+  return { canonicalPem, privateKey, publicDetails };
+}
+
+function writePrivateFile(filePath, contents) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempFile = `${filePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  fs.writeFileSync(tempFile, contents, { flag: 'wx', mode: 0o600 });
+  try {
+    fs.renameSync(tempFile, filePath);
+    fs.chmodSync(filePath, 0o600);
+  } finally {
+    try {
+      fs.unlinkSync(tempFile);
+    } catch {
+      // The rename already consumed the temporary file.
+    }
+  }
+}
+
+function loadOrCreateFarmingNetSigningIdentity(options = {}) {
+  const privateKeyFile = options.privateKeyFile;
+  const publicKeyFile = options.publicKeyFile;
+  if (!privateKeyFile || !publicKeyFile) {
+    throw new Error('Farming Net signing key paths are required');
+  }
+
+  let privateKeyPem = '';
+  try {
+    privateKeyPem = fs.readFileSync(privateKeyFile, 'utf8');
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+    const generated = crypto.generateKeyPairSync('ed25519');
+    const generatedPem = generated.privateKey.export({ format: 'pem', type: 'pkcs8' }).toString();
+    try {
+      fs.mkdirSync(path.dirname(privateKeyFile), { recursive: true });
+      fs.writeFileSync(privateKeyFile, generatedPem, { flag: 'wx', mode: 0o600 });
+      privateKeyPem = generatedPem;
+    } catch (writeError) {
+      if (!writeError || writeError.code !== 'EEXIST') throw writeError;
+      privateKeyPem = fs.readFileSync(privateKeyFile, 'utf8');
+    }
+  }
+
+  const details = privateKeyDetails(privateKeyPem);
+  fs.chmodSync(privateKeyFile, 0o600);
+  writePrivateFile(publicKeyFile, details.publicDetails.canonicalPem);
+  return {
+    issuer: details.publicDetails.issuer,
+    privateKey: details.privateKey,
+    privateKeyFile,
+    publicKey: details.publicDetails.publicKey,
+    publicKeyFile,
+    publicKeyPem: details.publicDetails.canonicalPem,
+  };
+}
+
+function encodeJsonSegment(value) {
+  return Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+}
+
+function decodeJsonSegment(segment) {
+  if (typeof segment !== 'string' || segment.length < 2 || segment.length > 2048) {
+    throw new Error('Invalid Farming Net pass segment');
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(segment)) {
+    throw new Error('Invalid Farming Net pass encoding');
+  }
+  const parsed = JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('Invalid Farming Net pass JSON');
+  }
+  return parsed;
+}
+
+function createFarmingNetPass(identity, options = {}) {
+  if (!identity || !identity.privateKey || !identity.issuer) {
+    throw new Error('Farming Net signing identity is required');
+  }
+  const audience = normalizeAudience(options.audience);
+  const subject = normalizeSubject(options.subject);
+  const nowSeconds = Math.floor(Number(options.nowMs ?? Date.now()) / 1000);
+  if (!Number.isSafeInteger(nowSeconds) || nowSeconds <= 0) {
+    throw new Error('Invalid Farming Net pass time');
+  }
+  const ttlSeconds = safeTtlSeconds(options.ttlSeconds);
+  const header = {
+    alg: 'EdDSA',
+    kid: normalizeIssuerId(identity.issuer),
+    typ: 'FarmingNetPass',
+  };
+  const payload = {
+    aud: audience,
+    exp: nowSeconds + ttlSeconds,
+    iat: nowSeconds,
+    iss: header.kid,
+    jti: crypto.randomBytes(18).toString('base64url'),
+    scope: PASS_SCOPE,
+    sub: subject,
+  };
+  const signingInput = `${encodeJsonSegment(header)}.${encodeJsonSegment(payload)}`;
+  const signature = crypto.sign(null, Buffer.from(signingInput, 'ascii'), identity.privateKey);
+  return `${signingInput}.${signature.toString('base64url')}`;
+}
+
+function normalizeFarmingNetTrust(rawTrust) {
+  if (!rawTrust || typeof rawTrust !== 'object' || Array.isArray(rawTrust)) {
+    throw new Error('Invalid Farming Net trust document');
+  }
+  const audience = normalizeAudience(rawTrust.audience);
+  const seenIssuers = new Set();
+  const issuers = (Array.isArray(rawTrust.issuers) ? rawTrust.issuers : []).map(rawIssuer => {
+    if (!rawIssuer || typeof rawIssuer !== 'object' || Array.isArray(rawIssuer)) {
+      throw new Error('Invalid Farming Net trusted issuer');
+    }
+    const id = normalizeIssuerId(rawIssuer.id);
+    const details = publicKeyDetails(rawIssuer.publicKey);
+    if (details.issuer !== id) {
+      throw new Error('Farming Net trusted issuer id does not match its public key');
+    }
+    if (seenIssuers.has(id)) throw new Error('Duplicate Farming Net trusted issuer');
+    seenIssuers.add(id);
+    return {
+      id,
+      name: String(rawIssuer.name || '').trim().slice(0, 80),
+      publicKey: details.canonicalPem,
+    };
+  });
+  if (issuers.length === 0 || issuers.length > 16) {
+    throw new Error('Farming Net trust requires between 1 and 16 issuers');
+  }
+  return { version: 1, audience, issuers };
+}
+
+function writeFarmingNetTrust(filePath, trust) {
+  const normalized = normalizeFarmingNetTrust(trust);
+  writePrivateFile(filePath, `${JSON.stringify(normalized, null, 2)}\n`);
+  return normalized;
+}
+
+function loadFarmingNetTrust(filePath) {
+  try {
+    return normalizeFarmingNetTrust(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+class FarmingNetPassVerifier {
+  constructor(options = {}) {
+    this.trustFile = String(options.trustFile || '');
+    this.seenPasses = new Map();
+  }
+
+  verify(pass, options = {}) {
+    try {
+      if (!this.trustFile) return { valid: false, reason: 'trust_not_configured' };
+      const trust = loadFarmingNetTrust(this.trustFile);
+      if (!trust) return { valid: false, reason: 'trust_not_configured' };
+      if (typeof pass !== 'string' || pass.length < 32 || pass.length > 4096) {
+        return { valid: false, reason: 'invalid_pass' };
+      }
+      const segments = pass.split('.');
+      if (segments.length !== 3 || !/^[A-Za-z0-9_-]+$/.test(segments[2])) {
+        return { valid: false, reason: 'invalid_pass' };
+      }
+      const header = decodeJsonSegment(segments[0]);
+      const payload = decodeJsonSegment(segments[1]);
+      if (header.alg !== 'EdDSA' || header.typ !== 'FarmingNetPass') {
+        return { valid: false, reason: 'invalid_header' };
+      }
+      const issuerId = normalizeIssuerId(header.kid);
+      const issuer = trust.issuers.find(item => item.id === issuerId);
+      if (!issuer || payload.iss !== issuerId) return { valid: false, reason: 'untrusted_issuer' };
+      if (payload.aud !== trust.audience) return { valid: false, reason: 'wrong_audience' };
+      if (payload.scope !== PASS_SCOPE) return { valid: false, reason: 'wrong_scope' };
+      normalizeSubject(payload.sub);
+      if (!Number.isSafeInteger(payload.iat) || !Number.isSafeInteger(payload.exp)) {
+        return { valid: false, reason: 'invalid_time' };
+      }
+      if (payload.exp <= payload.iat || payload.exp - payload.iat > MAX_PASS_TTL_SECONDS) {
+        return { valid: false, reason: 'invalid_lifetime' };
+      }
+      const nowSeconds = Math.floor(Number(options.nowMs ?? Date.now()) / 1000);
+      if (!Number.isSafeInteger(nowSeconds) || nowSeconds < payload.iat - CLOCK_SKEW_SECONDS) {
+        return { valid: false, reason: 'not_yet_valid' };
+      }
+      if (nowSeconds >= payload.exp) return { valid: false, reason: 'expired' };
+      if (typeof payload.jti !== 'string' || !/^[A-Za-z0-9_-]{16,128}$/.test(payload.jti)) {
+        return { valid: false, reason: 'invalid_jti' };
+      }
+
+      const publicKey = publicKeyDetails(issuer.publicKey).publicKey;
+      const signature = Buffer.from(segments[2], 'base64url');
+      const signingInput = Buffer.from(`${segments[0]}.${segments[1]}`, 'ascii');
+      if (!crypto.verify(null, signingInput, publicKey, signature)) {
+        return { valid: false, reason: 'invalid_signature' };
+      }
+
+      for (const [key, expiresAt] of this.seenPasses) {
+        if (expiresAt <= nowSeconds) this.seenPasses.delete(key);
+      }
+      const replayKey = `${issuerId}:${payload.jti}`;
+      if (this.seenPasses.has(replayKey)) return { valid: false, reason: 'replayed' };
+      this.seenPasses.set(replayKey, payload.exp);
+      return { valid: true, payload };
+    } catch {
+      return { valid: false, reason: 'invalid_pass' };
+    }
+  }
+}
+
+module.exports = {
+  CLOCK_SKEW_SECONDS,
+  DEFAULT_PASS_TTL_SECONDS,
+  FarmingNetPassVerifier,
+  MAX_PASS_TTL_SECONDS,
+  PASS_QUERY_PARAM,
+  PASS_SCOPE,
+  createFarmingNetPass,
+  loadFarmingNetTrust,
+  loadOrCreateFarmingNetSigningIdentity,
+  normalizeFarmingNetTrust,
+  writeFarmingNetTrust,
+};

package/backend/farming-net-registry.js

@@ -0,0 +1,112 @@
+const fs = require('fs');
+const path = require('path');
+
+const ENDPOINT_SCOPES = new Set(['this-device', 'intranet', 'remote', 'tunnel']);
+
+function boundedText(value, maxLength) {
+  return String(value || '').trim().slice(0, maxLength);
+}
+
+function normalizeEndpointUrl(value) {
+  try {
+    const url = new URL(String(value || '').trim());
+    if (!['http:', 'https:'].includes(url.protocol)) return '';
+    if (url.username || url.password) return '';
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+  } catch {
+    return '';
+  }
+}
+
+function normalizeEndpoint(rawEndpoint) {
+  if (!rawEndpoint || typeof rawEndpoint !== 'object' || Array.isArray(rawEndpoint)) return null;
+  const url = normalizeEndpointUrl(rawEndpoint.url);
+  if (!url) return null;
+  const scope = ENDPOINT_SCOPES.has(rawEndpoint.scope) ? rawEndpoint.scope : 'remote';
+  return {
+    label: boundedText(rawEndpoint.label, 40) || 'Open',
+    url,
+    scope,
+    primary: rawEndpoint.primary === true,
+  };
+}
+
+function normalizeInstance(rawInstance) {
+  if (!rawInstance || typeof rawInstance !== 'object' || Array.isArray(rawInstance)) return null;
+  const id = boundedText(rawInstance.id, 64).toLowerCase();
+  const name = boundedText(rawInstance.name, 80);
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(id) || !name) return null;
+
+  const seenUrls = new Set();
+  const endpoints = (Array.isArray(rawInstance.endpoints) ? rawInstance.endpoints : [])
+    .map(normalizeEndpoint)
+    .filter(Boolean)
+    .filter(endpoint => {
+      if (seenUrls.has(endpoint.url)) return false;
+      seenUrls.add(endpoint.url);
+      return true;
+    })
+    .slice(0, 8);
+  if (endpoints.length === 0) return null;
+  if (!endpoints.some(endpoint => endpoint.primary)) endpoints[0].primary = true;
+
+  return {
+    id,
+    name,
+    owner: boundedText(rawInstance.owner, 80),
+    description: boundedText(rawInstance.description, 180),
+    federated: rawInstance.federated === true,
+    platform: boundedText(rawInstance.platform, 40),
+    pinned: rawInstance.pinned === true,
+    endpoints,
+  };
+}
+
+function normalizeFarmingNetRegistry(rawRegistry) {
+  const source = rawRegistry && typeof rawRegistry === 'object' && !Array.isArray(rawRegistry)
+    ? rawRegistry
+    : {};
+  const seenIds = new Set();
+  const instances = (Array.isArray(source.instances) ? source.instances : [])
+    .map(normalizeInstance)
+    .filter(Boolean)
+    .filter(instance => {
+      if (seenIds.has(instance.id)) return false;
+      seenIds.add(instance.id);
+      return true;
+    })
+    .slice(0, 200);
+
+  return {
+    version: 1,
+    title: boundedText(source.title, 80) || 'Farming Net',
+    subtitle: boundedText(source.subtitle, 160),
+    instances,
+  };
+}
+
+function writeFarmingNetRegistry(filePath, registry) {
+  const normalized = normalizeFarmingNetRegistry(registry);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
+  return normalized;
+}
+
+function loadFarmingNetRegistry(filePath) {
+  try {
+    return normalizeFarmingNetRegistry(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
+    return writeFarmingNetRegistry(filePath, { version: 1, title: 'Farming Net', instances: [] });
+  }
+}
+
+module.exports = {
+  ENDPOINT_SCOPES,
+  loadFarmingNetRegistry,
+  normalizeEndpointUrl,
+  normalizeFarmingNetRegistry,
+  writeFarmingNetRegistry,
+};