@tokensmind/agent-network 0.1.0

package/src/runtime/portableStore.js

@@ -0,0 +1,193 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as defaultFs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const RECORD_NAMES = new Set(['active', 'pending', 'instance']);
+const PENDING_PHASES = new Set(['prepared', 'authorizing', 'authorized']);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const DEVICE_CODE_PATTERN = /^tm_device_[A-Za-z0-9_-]{43}$/;
+const AGENT_TOKEN_PATTERN = /^tm_agent_[A-Za-z0-9_-]{43}$/;
+
+function requireHomeDirectory(homeDir) {
+  const value = String(homeDir || '').trim();
+  if (!value) throw new Error('Unable to resolve the current user home directory');
+  return value;
+}
+
+export function resolvePortableStateDir({
+  platform = process.platform,
+  homeDir = os.homedir(),
+} = {}) {
+  const pathApi = platform === 'win32' ? path.win32 : path;
+  return pathApi.join(requireHomeDirectory(homeDir), '.tokensmind', 'agent-network');
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isOperation(value) {
+  return isObject(value)
+    && ['GET', 'POST', 'PATCH', 'DELETE'].includes(value.method)
+    && isNonEmptyString(value.path);
+}
+
+function isInstance(value) {
+  return isObject(value) && UUID_PATTERN.test(value.id);
+}
+
+function isActive(value) {
+  return isObject(value)
+    && AGENT_TOKEN_PATTERN.test(value.token)
+    && (value.agentId === null || isNonEmptyString(value.agentId))
+    && isNonEmptyString(value.credentialId)
+    && isNonEmptyString(value.tokenPrefix)
+    && value.token.startsWith(value.tokenPrefix);
+}
+
+function hasPendingSecrets(value) {
+  return UUID_PATTERN.test(value.authorizationId)
+    && UUID_PATTERN.test(value.instanceId)
+    && UUID_PATTERN.test(value.createIdempotencyKey)
+    && UUID_PATTERN.test(value.exchangeIdempotencyKey)
+    && DEVICE_CODE_PATTERN.test(value.deviceCode)
+    && SHA256_PATTERN.test(value.deviceCodeHash)
+    && AGENT_TOKEN_PATTERN.test(value.token)
+    && SHA256_PATTERN.test(value.tokenHash)
+    && isNonEmptyString(value.tokenPrefix)
+    && value.token.startsWith(value.tokenPrefix);
+}
+
+function hasAuthorization(value) {
+  return isObject(value.authorization)
+    && value.authorization.authorizationId === value.authorizationId
+    && isNonEmptyString(value.authorization.verificationUrl)
+    && Number.isFinite(Date.parse(value.authorization.expiresAt))
+    && Number.isInteger(value.authorization.intervalSeconds)
+    && value.authorization.intervalSeconds > 0;
+}
+
+function isPending(value) {
+  if (!isObject(value) || !PENDING_PHASES.has(value.phase)) return false;
+  if (!isOperation(value.operation) || !hasPendingSecrets(value)) return false;
+  return value.phase === 'prepared' || hasAuthorization(value);
+}
+
+export function validatePortableRecord(name, value) {
+  const valid = name === 'active'
+    ? isActive(value)
+    : name === 'pending'
+      ? isPending(value)
+      : isInstance(value);
+  if (!valid) throw new Error(`Portable Agent Network ${name} state has an invalid structure`);
+}
+
+function validateRecordName(name) {
+  if (!RECORD_NAMES.has(name)) throw new Error(`Unsupported portable state record: ${name}`);
+}
+
+export function originNamespace(origin) {
+  const url = new URL(origin);
+  if (!['http:', 'https:'].includes(url.protocol) || url.origin !== origin) {
+    throw new Error('Portable Agent Network store requires a normalized HTTP origin');
+  }
+  return createHash('sha256').update(origin, 'utf8').digest('hex');
+}
+
+function isMissing(error) {
+  return error?.code === 'ENOENT';
+}
+
+async function ensurePrivateDirectory({ fs, directory, platform }) {
+  await fs.mkdir(directory, { recursive: true, mode: DIRECTORY_MODE });
+  if (platform !== 'win32') await fs.chmod(directory, DIRECTORY_MODE);
+}
+
+async function removeTemporaryFile(fs, filePath) {
+  try {
+    await fs.unlink(filePath);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+}
+
+function createReadOperation({ fs, recordPath }) {
+  return async function read(name) {
+    validateRecordName(name);
+    let source;
+    try {
+      source = await fs.readFile(recordPath(name), 'utf8');
+    } catch (error) {
+      if (isMissing(error)) return null;
+      throw error;
+    }
+    let value;
+    try {
+      value = JSON.parse(source);
+    } catch (error) {
+      throw new Error(`Portable Agent Network ${name} state is invalid JSON`, { cause: error });
+    }
+    validatePortableRecord(name, value);
+    return value;
+  };
+}
+
+function createWriteOperation({ fs, directory, platform, randomId, recordPath }) {
+  return async function write(name, value) {
+    validateRecordName(name);
+    validatePortableRecord(name, value);
+    await ensurePrivateDirectory({ fs, directory, platform });
+    const target = recordPath(name);
+    const temporary = path.join(directory, `.${name}.${process.pid}.${randomId()}.tmp`);
+    try {
+      await fs.writeFile(temporary, JSON.stringify(value), {
+        encoding: 'utf8', mode: FILE_MODE, flag: 'wx',
+      });
+      if (platform !== 'win32') await fs.chmod(temporary, FILE_MODE);
+      await fs.rename(temporary, target);
+      if (platform !== 'win32') await fs.chmod(target, FILE_MODE);
+    } catch (error) {
+      await removeTemporaryFile(fs, temporary);
+      throw error;
+    }
+  };
+}
+
+function createRemoveOperation({ fs, recordPath }) {
+  return async function remove(name) {
+    validateRecordName(name);
+    try {
+      await fs.unlink(recordPath(name));
+    } catch (error) {
+      if (!isMissing(error)) throw error;
+    }
+  };
+}
+
+export function createPortableStore({
+  stateDir,
+  origin,
+  platform = process.platform,
+  env = process.env,
+  homeDir = os.homedir(),
+  fs = defaultFs,
+  randomId = randomUUID,
+} = {}) {
+  const baseDirectory = path.resolve(stateDir || resolvePortableStateDir({ platform, env, homeDir }));
+  const directory = path.join(baseDirectory, originNamespace(origin));
+  const recordPath = (name) => path.join(directory, `${name}.json`);
+  const context = { fs, directory, platform, randomId, recordPath };
+  return {
+    read: createReadOperation(context),
+    write: createWriteOperation(context),
+    remove: createRemoveOperation(context),
+  };
+}

package/src/runtime/requestPolicy.js

@@ -0,0 +1,55 @@
+import { INTERNAL_PATH_PATTERNS, MUTATION_METHODS } from './constants.js';
+
+const SUPPORTED_METHODS = new Set(['GET', 'POST', 'PATCH', 'DELETE']);
+const PUBLIC_AGENT_DIRECTORY_PATH = '/agent-network-api/agents';
+
+export function normalizeBaseUrl(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Agent Network baseUrl must use http or https');
+  }
+  url.pathname = '/';
+  url.search = '';
+  url.hash = '';
+  return url.origin;
+}
+
+export function validateBusinessRequest({ method, path, idempotencyKey, reauthorize }) {
+  const normalizedMethod = String(method).toUpperCase();
+  if (!SUPPORTED_METHODS.has(normalizedMethod)) {
+    throw new Error(`Unsupported Agent Network method: ${normalizedMethod}`);
+  }
+  if (!path.startsWith('/agent-network-api/')) {
+    throw new Error('Agent Network path must start with /agent-network-api/');
+  }
+  if (INTERNAL_PATH_PATTERNS.some((pattern) => pattern.test(path))) {
+    throw new Error('This endpoint is not available through the ordinary-user connector');
+  }
+  if (MUTATION_METHODS.has(normalizedMethod) && !idempotencyKey?.trim()) {
+    throw new Error('Mutating Agent Network requests require a stable Idempotency-Key');
+  }
+  if (reauthorize !== undefined && typeof reauthorize !== 'boolean') {
+    throw new Error('Agent Network reauthorize must be a boolean');
+  }
+  return { method: normalizedMethod, path, idempotencyKey: idempotencyKey?.trim() };
+}
+
+export function buildBusinessUrl(baseUrl, path) {
+  const url = new URL(path, `${baseUrl}/`);
+  if (url.origin !== baseUrl || !url.pathname.startsWith('/agent-network-api/')) {
+    throw new Error('Agent Network request must remain on the configured origin');
+  }
+  if (INTERNAL_PATH_PATTERNS.some((pattern) => pattern.test(url.pathname))) {
+    throw new Error('This endpoint is not available through the ordinary-user connector');
+  }
+  return url.toString();
+}
+
+export function isPublicDiscoveryRequest({ method, path }) {
+  if (method !== 'GET') return false;
+  const url = new URL(path, 'https://tokensmind.invalid');
+  const mineRequested = [...url.searchParams.entries()]
+    .some(([key, value]) => key === 'mine' && value === '1');
+  return url.pathname === PUBLIC_AGENT_DIRECTORY_PATH
+    && !mineRequested;
+}

package/src/runtime/systemCredentialStore.js

@@ -0,0 +1,176 @@
+import { spawn as defaultSpawn } from 'node:child_process';
+import { constants as fsConstants, promises as defaultFs } from 'node:fs';
+import path from 'node:path';
+import { validatePortableRecord } from './portableStore.js';
+
+const SERVICE_NAME = 'TokensMind Agent Network';
+const APPLICATION_NAME = 'tokensmind-agent-network';
+const RECORD_NAMES = new Set(['active', 'pending', 'instance']);
+const MACOS_SECURITY_PATH = '/usr/bin/security';
+const MACOS_ITEM_NOT_FOUND = 44;
+
+function validateRecordName(name) {
+  if (!RECORD_NAMES.has(name)) throw new Error(`Unsupported portable state record: ${name}`);
+}
+
+function credentialAccount(namespace, name) {
+  validateRecordName(name);
+  return `${namespace}:${name}`;
+}
+
+function parseRecord(name, source) {
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch (error) {
+    throw new Error(`System Agent Network ${name} credential is invalid JSON`, { cause: error });
+  }
+  validatePortableRecord(name, value);
+  return value;
+}
+
+function commandFailure(backend, operation, result) {
+  return new Error(
+    `${backend} ${operation} failed with exit code ${String(result.code)}`,
+  );
+}
+
+export function createCommandRunner({ spawnImpl = defaultSpawn } = {}) {
+  return ({ command, args, input = '' }) => new Promise((resolve, reject) => {
+    const child = spawnImpl(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const stdout = [];
+    const stderr = [];
+    let settled = false;
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.stdin.on('error', (error) => {
+      if (error.code === 'EPIPE' || settled) return;
+      settled = true;
+      reject(error);
+    });
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      resolve({
+        code,
+        stdout: Buffer.concat(stdout).toString('utf8'),
+        stderr: Buffer.concat(stderr).toString('utf8'),
+      });
+    });
+    child.stdin.end(input);
+  });
+}
+
+function createMacOperations({ namespace, run }) {
+  return {
+    async read(name) {
+      const account = credentialAccount(namespace, name);
+      const result = await run({
+        command: MACOS_SECURITY_PATH,
+        args: ['find-generic-password', '-a', account, '-s', SERVICE_NAME, '-w'],
+      });
+      if (result.code === MACOS_ITEM_NOT_FOUND) return null;
+      if (result.code !== 0) throw commandFailure('macOS Keychain', 'read', result);
+      return parseRecord(name, result.stdout.trim());
+    },
+    async write(name, value) {
+      validateRecordName(name);
+      validatePortableRecord(name, value);
+      const account = credentialAccount(namespace, name);
+      const result = await run({
+        command: MACOS_SECURITY_PATH,
+        args: ['add-generic-password', '-a', account, '-s', SERVICE_NAME, '-U', '-w'],
+        input: `${JSON.stringify(value)}\n`,
+      });
+      if (result.code !== 0) throw commandFailure('macOS Keychain', 'write', result);
+    },
+    async remove(name) {
+      const account = credentialAccount(namespace, name);
+      const result = await run({
+        command: MACOS_SECURITY_PATH,
+        args: ['delete-generic-password', '-a', account, '-s', SERVICE_NAME],
+      });
+      if (![0, MACOS_ITEM_NOT_FOUND].includes(result.code)) {
+        throw commandFailure('macOS Keychain', 'remove', result);
+      }
+    },
+  };
+}
+
+function linuxAttributes(namespace, name) {
+  validateRecordName(name);
+  return ['application', APPLICATION_NAME, 'origin', namespace, 'record', name];
+}
+
+function createLinuxOperations({ namespace, command, run }) {
+  async function lookup(name) {
+    const result = await run({
+      command,
+      args: ['lookup', ...linuxAttributes(namespace, name)],
+    });
+    const missing = result.code === 1 && !result.stdout.trim() && !result.stderr.trim();
+    if (missing) return null;
+    if (result.code !== 0) throw commandFailure('Linux Secret Service', 'read', result);
+    return parseRecord(name, result.stdout.trim());
+  }
+  return {
+    read: lookup,
+    async write(name, value) {
+      validatePortableRecord(name, value);
+      const result = await run({
+        command,
+        args: ['store', `--label=${SERVICE_NAME}`, ...linuxAttributes(namespace, name)],
+        input: `${JSON.stringify(value)}\n`,
+      });
+      if (result.code !== 0) throw commandFailure('Linux Secret Service', 'write', result);
+    },
+    async remove(name) {
+      if (await lookup(name) === null) return;
+      const result = await run({
+        command,
+        args: ['clear', ...linuxAttributes(namespace, name)],
+      });
+      if (result.code !== 0) throw commandFailure('Linux Secret Service', 'remove', result);
+    },
+  };
+}
+
+async function isExecutable(fs, filePath) {
+  try {
+    await fs.access(filePath, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findExecutable({ name, env, fs }) {
+  const directories = String(env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const directory of directories) {
+    const candidate = path.join(directory, name);
+    if (await isExecutable(fs, candidate)) return candidate;
+  }
+  return null;
+}
+
+export async function resolveSystemCredentialStore({
+  platform,
+  namespace,
+  env = process.env,
+  fs = defaultFs,
+  run = createCommandRunner(),
+} = {}) {
+  if (platform === 'darwin') {
+    if (!await isExecutable(fs, MACOS_SECURITY_PATH)) return null;
+    return createMacOperations({ namespace, run });
+  }
+  if (platform === 'linux') {
+    const command = await findExecutable({ name: 'secret-tool', env, fs });
+    return command ? createLinuxOperations({ namespace, command, run }) : null;
+  }
+  return null;
+}

package/src/workflow-store.js

@@ -0,0 +1,77 @@
+import { promises as defaultFs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { originNamespace, resolvePortableStateDir } from './runtime/portableStore.js';
+
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+
+function recordPath({ stateDir, origin, platform, homeDir }) {
+  const base = stateDir || resolvePortableStateDir({ platform, homeDir });
+  return path.join(path.resolve(base), originNamespace(origin), 'workflow.json');
+}
+
+async function ensureDirectory(fs, filePath, platform) {
+  const directory = path.dirname(filePath);
+  await fs.mkdir(directory, { recursive: true, mode: DIRECTORY_MODE });
+  if (platform !== 'win32') await fs.chmod(directory, DIRECTORY_MODE);
+}
+
+async function writeCandidate({ fs, filePath, platform, value }) {
+  const temporary = path.join(path.dirname(filePath), `.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    await fs.writeFile(temporary, JSON.stringify(value), {
+      encoding: 'utf8', mode: FILE_MODE, flag: 'wx',
+    });
+    if (platform !== 'win32') await fs.chmod(temporary, FILE_MODE);
+    try {
+      await fs.link(temporary, filePath);
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+  } finally {
+    try {
+      await fs.unlink(temporary);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+export function createWorkflowStore({
+  stateDir,
+  origin,
+  platform = process.platform,
+  homeDir = os.homedir(),
+  fs = defaultFs,
+} = {}) {
+  const filePath = recordPath({ stateDir, origin, platform, homeDir });
+  return {
+    async read(name = 'workflow') {
+      if (name !== 'workflow') throw new Error(`Unsupported workflow record: ${name}`);
+      try {
+        return JSON.parse(await fs.readFile(filePath, 'utf8'));
+      } catch (error) {
+        if (error?.code === 'ENOENT') return null;
+        if (error instanceof SyntaxError) throw new Error('Workflow state is invalid JSON', { cause: error });
+        throw error;
+      }
+    },
+    async write(name, value) {
+      if (name !== 'workflow') throw new Error(`Unsupported workflow record: ${name}`);
+      await ensureDirectory(fs, filePath, platform);
+      await writeCandidate({ fs, filePath, platform, value });
+    },
+    async remove(name = 'workflow') {
+      if (name !== 'workflow') throw new Error(`Unsupported workflow record: ${name}`);
+      try {
+        await fs.unlink(filePath);
+        return true;
+      } catch (error) {
+        if (error?.code === 'ENOENT') return false;
+        throw error;
+      }
+    },
+  };
+}