arcway 0.1.27 → 0.1.28

package/server/lib/vault/secrets.js

@@ -0,0 +1,149 @@
+import { createECDH, hkdfSync, randomBytes } from 'node:crypto';
+
+const MASTER_VERSION = 'v1';
+const MASTER_BYTES = 32;
+const VAULT_KEY_BYTES = 32;
+const HKDF_SALT = 'arcway:infra-secrets:v1';
+
+const SECRET_NAMES = Object.freeze([
+  'session',
+  'plugin-vault',
+  'mcp-api',
+  'pty-api',
+  'pty-server-api',
+  'vapid',
+]);
+
+function base64Url(buffer) {
+  return Buffer.from(buffer).toString('base64url');
+}
+
+function encodeMasterSecret(key = randomBytes(MASTER_BYTES)) {
+  if (!Buffer.isBuffer(key) || key.length !== MASTER_BYTES) {
+    throw new Error(`Arcway master secret must be ${MASTER_BYTES} bytes`);
+  }
+  return `${MASTER_VERSION}:${key.toString('base64')}`;
+}
+
+function decodeVersionedSecret(value, label = 'Arcway master secret') {
+  const trimmed = String(value ?? '').trim();
+  const [version, encoded] = trimmed.split(':');
+  if (version !== MASTER_VERSION || !encoded || trimmed.split(':').length !== 2) {
+    throw new Error(
+      `${label} must use ${MASTER_VERSION}:<base64-32-byte-key> or a 32+ character string`,
+    );
+  }
+
+  const key = Buffer.from(encoded, 'base64');
+  if (key.length !== MASTER_BYTES || key.toString('base64') !== encoded) {
+    throw new Error(`${label} must decode to ${MASTER_BYTES} bytes`);
+  }
+  return key;
+}
+
+function normalizeMasterSecret(value, label = 'Arcway master secret') {
+  if (Buffer.isBuffer(value)) {
+    if (value.length < MASTER_BYTES)
+      throw new Error(`${label} must be at least ${MASTER_BYTES} bytes`);
+    return value;
+  }
+
+  if (typeof value !== 'string') {
+    throw new Error(`${label} must be a string or Buffer`);
+  }
+
+  const trimmed = value.trim();
+  if (trimmed.startsWith(`${MASTER_VERSION}:`)) return decodeVersionedSecret(trimmed, label);
+  if (trimmed.length < MASTER_BYTES) {
+    throw new Error(`${label} must be at least ${MASTER_BYTES} characters`);
+  }
+  return Buffer.from(trimmed, 'utf8');
+}
+
+function deriveBytes(master, namespace, length = MASTER_BYTES) {
+  const key = normalizeMasterSecret(master);
+  return Buffer.from(hkdfSync('sha256', key, HKDF_SALT, `arcway:${namespace}`, length));
+}
+
+function formatVaultKey(bytes) {
+  const key = Buffer.from(bytes);
+  if (key.length !== VAULT_KEY_BYTES) {
+    throw new Error(`Vault key material must be ${VAULT_KEY_BYTES} bytes`);
+  }
+  return `${MASTER_VERSION}:${key.toString('base64')}`;
+}
+
+function validateVaultKey(value, label = 'plugin-vault secret') {
+  return formatVaultKey(decodeVersionedSecret(value, label));
+}
+
+function deriveVapidKeyPair(master) {
+  for (let i = 0; i < 32; i += 1) {
+    const privateKey = deriveBytes(master, `vapid:private:${i}`, 32);
+    try {
+      const ecdh = createECDH('prime256v1');
+      ecdh.setPrivateKey(privateKey);
+      return {
+        publicKey: base64Url(ecdh.getPublicKey(null, 'uncompressed')),
+        privateKey: base64Url(privateKey),
+      };
+    } catch {
+      // Try the next deterministic candidate.
+    }
+  }
+  throw new Error('Unable to derive a valid deterministic VAPID keypair');
+}
+
+function deriveInfraSecret(master, name) {
+  if (name === 'session') return base64Url(deriveBytes(master, name, 48));
+  if (name === 'plugin-vault') return formatVaultKey(deriveBytes(master, name, VAULT_KEY_BYTES));
+  if (name === 'mcp-api') return base64Url(deriveBytes(master, name, 48));
+  if (name === 'pty-api') return base64Url(deriveBytes(master, name, 48));
+  if (name === 'pty-server-api') return base64Url(deriveBytes(master, name, 48));
+  if (name === 'vapid') return deriveVapidKeyPair(master);
+  throw new Error(`Unknown Arcway infra secret namespace: ${name}`);
+}
+
+function deriveInfraSecrets(master) {
+  const values = {};
+  for (const name of SECRET_NAMES) {
+    values[name] = deriveInfraSecret(master, name);
+  }
+  return values;
+}
+
+function decryptWithRotation(ciphertext, { current, previous, decrypt, encrypt, onRotate } = {}) {
+  if (typeof decrypt !== 'function') throw new Error('decryptWithRotation requires decrypt');
+  if (typeof encrypt !== 'function') throw new Error('decryptWithRotation requires encrypt');
+  if (!current) throw new Error('decryptWithRotation requires current secret');
+
+  try {
+    return { plaintext: decrypt(ciphertext, current), rotated: false };
+  } catch (currentError) {
+    const previousValues = Array.isArray(previous)
+      ? previous.filter(Boolean)
+      : [previous].filter(Boolean);
+    for (const previousSecret of previousValues) {
+      try {
+        const plaintext = decrypt(ciphertext, previousSecret);
+        const rotatedCiphertext = encrypt(plaintext, current);
+        onRotate?.(rotatedCiphertext);
+        return { plaintext, rotated: true, rotatedCiphertext };
+      } catch {}
+    }
+    throw currentError;
+  }
+}
+
+export {
+  SECRET_NAMES,
+  decryptWithRotation,
+  deriveBytes,
+  deriveInfraSecret,
+  deriveInfraSecrets,
+  deriveVapidKeyPair,
+  encodeMasterSecret,
+  formatVaultKey,
+  normalizeMasterSecret,
+  validateVaultKey,
+};

package/server/plugins/capabilities.js

@@ -0,0 +1,66 @@
+import { requiredCapabilities } from './manifest.js';
+
+class CapabilityNotAvailable extends Error {
+  constructor(capability, reason = 'missing or disabled') {
+    super(`Capability not available: ${capability} (${reason})`);
+    this.name = 'CapabilityNotAvailable';
+    this.capability = capability;
+    this.reason = reason;
+  }
+}
+
+class CapabilityRegistry {
+  #providers = new Map();
+
+  register(pluginId, capability, factory) {
+    if (typeof factory !== 'function') {
+      throw new Error(
+        `Capability ${capability} from plugin ${pluginId} must be registered with a factory`,
+      );
+    }
+    if (this.#providers.has(capability)) {
+      const existing = this.#providers.get(capability);
+      throw new Error(
+        `Capability ${capability} is already provided by plugin ${existing.pluginId}`,
+      );
+    }
+    this.#providers.set(capability, { pluginId, factory, enabled: true });
+  }
+
+  setPluginEnabled(pluginId, enabled) {
+    for (const provider of this.#providers.values()) {
+      if (provider.pluginId === pluginId) provider.enabled = enabled;
+    }
+  }
+
+  has(capability) {
+    const provider = this.#providers.get(capability);
+    return provider?.enabled === true;
+  }
+
+  inject(ctx, requires) {
+    for (const capability of requiredCapabilities(requires)) {
+      const provider = this.#providers.get(capability);
+      if (!provider) throw new CapabilityNotAvailable(capability, 'missing provider');
+      if (!provider.enabled) throw new CapabilityNotAvailable(capability, 'provider disabled');
+      ctx[capability] = provider.factory({
+        capability,
+        providerPluginId: provider.pluginId,
+        req: ctx.req,
+        session: ctx.req?.session,
+        ctx,
+      });
+    }
+    return ctx;
+  }
+
+  list() {
+    return [...this.#providers.entries()].map(([capability, provider]) => ({
+      capability,
+      pluginId: provider.pluginId,
+      enabled: provider.enabled,
+    }));
+  }
+}
+
+export { CapabilityNotAvailable, CapabilityRegistry };

package/server/plugins/discovery.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { discoverPackageDirectories } from '../discovery.js';
+import { loadModule } from '../module-loader.js';
+import { validateManifest } from './manifest.js';
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+async function readJson(filePath, label) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Failed to read ${label} at ${filePath}: ${err}`);
+  }
+}
+
+function getManifest(module, manifestPath) {
+  const manifest = module.manifest ?? module.default?.manifest ?? module.default;
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error(`Plugin manifest at ${manifestPath} must export a manifest object`);
+  }
+  return manifest;
+}
+
+async function loadPluginPackage(packageDir) {
+  const packageJsonPath = path.join(packageDir, 'package.json');
+  if (!(await exists(packageJsonPath))) {
+    throw new Error(`Plugin package at ${packageDir} must include package.json`);
+  }
+  const packageJson = await readJson(packageJsonPath, 'package.json');
+
+  const pluginJs = path.join(packageDir, 'plugin.js');
+  const pluginJson = path.join(packageDir, 'plugin.json');
+  let manifestPath;
+  let module = {};
+  let rawManifest;
+
+  if (await exists(pluginJs)) {
+    manifestPath = pluginJs;
+    module = await loadModule(pluginJs, import.meta.url);
+    rawManifest = getManifest(module, pluginJs);
+  } else if (await exists(pluginJson)) {
+    manifestPath = pluginJson;
+    rawManifest = await readJson(pluginJson, 'plugin.json');
+  } else {
+    throw new Error(`Plugin package at ${packageDir} must include plugin.js or plugin.json`);
+  }
+
+  const manifest = validateManifest(
+    {
+      version: packageJson.version,
+      name: packageJson.name,
+      ...rawManifest,
+    },
+    { packageName: packageJson.name },
+  );
+
+  const routesDir = path.join(packageDir, 'routes');
+  const jobsDir = path.join(packageDir, 'jobs');
+  const migrationsDir =
+    typeof manifest.contributes.migrations === 'string'
+      ? path.join(packageDir, manifest.contributes.migrations)
+      : path.join(packageDir, 'migrations');
+
+  return {
+    id: manifest.id,
+    dir: packageDir,
+    packageJson,
+    manifest,
+    module,
+    manifestPath,
+    routesDir: (await exists(routesDir)) ? routesDir : null,
+    jobsDir: (await exists(jobsDir)) ? jobsDir : null,
+    migrationsDir: (await exists(migrationsDir)) ? migrationsDir : null,
+  };
+}
+
+async function discoverPlugins(dirs) {
+  const plugins = [];
+  const seen = new Map();
+
+  for (const dir of dirs ?? []) {
+    const packages = await discoverPackageDirectories(dir, {
+      markerFiles: ['plugin.js', 'plugin.json'],
+      label: 'plugin',
+    });
+    for (const entry of packages) {
+      const plugin = await loadPluginPackage(entry.dir);
+      if (seen.has(plugin.id)) {
+        throw new Error(
+          `Duplicate plugin id ${plugin.id} in ${seen.get(plugin.id)} and ${plugin.dir}`,
+        );
+      }
+      seen.set(plugin.id, plugin.dir);
+      plugins.push(plugin);
+    }
+  }
+
+  plugins.sort((a, b) => a.id.localeCompare(b.id));
+  return plugins;
+}
+
+export { discoverPlugins, loadPluginPackage };

package/server/plugins/graph.js

@@ -0,0 +1,114 @@
+import { requiredCapabilities } from './manifest.js';
+
+function buildProviderMap(plugins) {
+  const providers = new Map();
+  for (const plugin of plugins) {
+    for (const capability of plugin.manifest.provides) {
+      if (providers.has(capability)) {
+        throw new Error(
+          `Capability ${capability} is provided by both ${providers.get(capability).id} and ${plugin.id}`,
+        );
+      }
+      providers.set(capability, plugin);
+    }
+  }
+  return providers;
+}
+
+function resolvePluginGraph(plugins, enabledIds) {
+  const allProviders = buildProviderMap(plugins);
+  const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
+  const enabled = new Set(enabledIds);
+  const missing = [];
+  const edges = new Map();
+
+  for (const plugin of plugins) {
+    edges.set(plugin.id, new Set());
+    if (!enabled.has(plugin.id)) continue;
+    for (const capability of requiredCapabilities(plugin.manifest.requires)) {
+      const provider = allProviders.get(capability);
+      if (!provider) {
+        missing.push({ pluginId: plugin.id, capability, reason: 'missing provider' });
+        continue;
+      }
+      if (!enabled.has(provider.id)) {
+        missing.push({
+          pluginId: plugin.id,
+          capability,
+          providerId: provider.id,
+          reason: 'provider disabled',
+        });
+        continue;
+      }
+      if (provider.id !== plugin.id) edges.get(provider.id).add(plugin.id);
+    }
+  }
+
+  if (missing.length > 0) {
+    const first = missing[0];
+    const provider = first.providerId ? ` from ${first.providerId}` : '';
+    throw new Error(
+      `Plugin ${first.pluginId} requires capability ${first.capability}${provider}: ${first.reason}`,
+    );
+  }
+
+  const indegree = new Map([...enabled].map((id) => [id, 0]));
+  for (const [providerId, dependents] of edges) {
+    if (!enabled.has(providerId)) continue;
+    for (const dependentId of dependents) {
+      if (enabled.has(dependentId)) indegree.set(dependentId, indegree.get(dependentId) + 1);
+    }
+  }
+
+  const ready = [...indegree.entries()]
+    .filter(([, degree]) => degree === 0)
+    .map(([id]) => id)
+    .sort();
+  const orderedIds = [];
+
+  while (ready.length > 0) {
+    const id = ready.shift();
+    orderedIds.push(id);
+    for (const dependentId of [...(edges.get(id) ?? [])].sort()) {
+      if (!enabled.has(dependentId)) continue;
+      indegree.set(dependentId, indegree.get(dependentId) - 1);
+      if (indegree.get(dependentId) === 0) ready.push(dependentId);
+    }
+    ready.sort();
+  }
+
+  if (orderedIds.length !== enabled.size) {
+    throw new Error('Plugin capability graph contains a cycle');
+  }
+
+  return {
+    providers: allProviders,
+    order: orderedIds.map((id) => byId.get(id)),
+    edges,
+  };
+}
+
+function cascadeDisabled(plugins, disabledIds) {
+  const providers = buildProviderMap(plugins);
+  const disabled = new Map([...disabledIds].map((id) => [id, 'disabled']));
+  let changed = true;
+
+  while (changed) {
+    changed = false;
+    for (const plugin of plugins) {
+      if (disabled.has(plugin.id)) continue;
+      for (const capability of requiredCapabilities(plugin.manifest.requires)) {
+        const provider = providers.get(capability);
+        if (!provider || disabled.has(provider.id)) {
+          disabled.set(plugin.id, `disabled (missing dependency: ${capability})`);
+          changed = true;
+          break;
+        }
+      }
+    }
+  }
+
+  return disabled;
+}
+
+export { buildProviderMap, cascadeDisabled, resolvePluginGraph };

package/server/plugins/manager.js

@@ -0,0 +1,210 @@
+import { discoverRoutes } from '../router/routes.js';
+import { discoverJobs } from '../jobs/runner.js';
+import { CapabilityRegistry } from './capabilities.js';
+import { discoverPlugins } from './discovery.js';
+import { buildProviderMap, cascadeDisabled, resolvePluginGraph } from './graph.js';
+import { requiredCapabilities } from './manifest.js';
+
+function configuredEnablements(config) {
+  const enablements = config?.enablements ?? config?.enabledPlugins ?? {};
+  return enablements && typeof enablements === 'object' ? enablements : {};
+}
+
+function pluginEnabledByDefault(plugin, enablements) {
+  if (Object.prototype.hasOwnProperty.call(enablements, plugin.id)) {
+    return enablements[plugin.id] === true;
+  }
+  return plugin.manifest.defaultEnabled === true;
+}
+
+function capabilityFactory(plugin, capability) {
+  return (
+    plugin.module.capabilities?.[capability] ??
+    plugin.module.default?.capabilities?.[capability] ??
+    plugin.module[`create${capability[0]?.toUpperCase() ?? ''}${capability.slice(1)}`]
+  );
+}
+
+class PluginManager {
+  constructor(config, { log, runLifecycle = true } = {}) {
+    this.config = config ?? { enabled: false, dirs: [] };
+    this.log = log;
+    this.runLifecycle = runLifecycle;
+    this.plugins = [];
+    this.enabled = new Set();
+    this.status = new Map();
+    this.loadOrder = [];
+    this.capabilities = new CapabilityRegistry();
+  }
+
+  async init() {
+    if (this.config.enabled !== true) return this;
+
+    this.plugins = await discoverPlugins(this.config.dirs);
+    const enablements = configuredEnablements(this.config);
+    this.enabled = new Set(
+      this.plugins
+        .filter((plugin) => pluginEnabledByDefault(plugin, enablements))
+        .map((plugin) => plugin.id),
+    );
+
+    this.#rebuildGraph();
+
+    for (const plugin of this.loadOrder) {
+      if (this.runLifecycle) {
+        await this.#runLifecycle(plugin, 'onLoad');
+        await this.#runLifecycle(plugin, 'onEnable');
+      }
+      this.log?.info?.(`Plugin enabled: ${plugin.id}`);
+    }
+    return this;
+  }
+
+  get enabledPlugins() {
+    return this.loadOrder;
+  }
+
+  getPlugin(id) {
+    return this.plugins.find((plugin) => plugin.id === id) ?? null;
+  }
+
+  async enable(id) {
+    const plugin = this.getPlugin(id);
+    if (!plugin) throw new Error(`Unknown plugin: ${id}`);
+    this.enabled.add(id);
+    this.#rebuildGraph();
+    if (this.runLifecycle) await this.#runLifecycle(plugin, 'onEnable');
+  }
+
+  async runEnabledLifecycle() {
+    for (const plugin of this.loadOrder) {
+      await this.#runLifecycle(plugin, 'onLoad');
+      await this.#runLifecycle(plugin, 'onEnable');
+    }
+    this.runLifecycle = true;
+  }
+
+  async disable(id) {
+    const plugin = this.getPlugin(id);
+    if (!plugin) throw new Error(`Unknown plugin: ${id}`);
+    this.enabled.delete(id);
+    if (this.runLifecycle) await this.#runLifecycle(plugin, 'onDisable');
+    this.#rebuildGraph();
+  }
+
+  injectCapabilities(ctx, requires) {
+    return this.capabilities.inject(ctx, requires);
+  }
+
+  async discoverRoutes() {
+    const routes = [];
+    for (const plugin of this.enabledPlugins) {
+      if (!plugin.routesDir) continue;
+      const discovered = await discoverRoutes(plugin.routesDir, {
+        prefix: `/plugins/${plugin.id}`,
+        plugin: {
+          id: plugin.id,
+          requires: plugin.manifest.requires,
+        },
+      });
+      routes.push(...discovered);
+    }
+    return routes;
+  }
+
+  async discoverJobs() {
+    const jobs = [];
+    for (const plugin of this.enabledPlugins) {
+      if (!plugin.jobsDir) continue;
+      const discovered = await discoverJobs(plugin.jobsDir);
+      for (const job of discovered) {
+        const definition = {
+          ...job.definition,
+          name: `plugins/${plugin.id}/${job.definition.name}`,
+          plugin: {
+            id: plugin.id,
+            requires: plugin.manifest.requires,
+          },
+        };
+        jobs.push({ ...job, definition, filePath: null });
+      }
+    }
+    return jobs;
+  }
+
+  migrations() {
+    return this.enabledPlugins
+      .filter((plugin) => plugin.migrationsDir)
+      .map((plugin) => ({
+        pluginId: plugin.id,
+        dir: plugin.migrationsDir,
+        contributes: plugin.manifest.contributes.migrations,
+      }));
+  }
+
+  #rebuildGraph() {
+    const providers = buildProviderMap(this.plugins);
+    for (const plugin of this.plugins) {
+      if (!this.enabled.has(plugin.id)) continue;
+      for (const capability of requiredCapabilities(plugin.manifest.requires)) {
+        if (!providers.has(capability)) {
+          throw new Error(
+            `Plugin ${plugin.id} requires capability ${capability}: missing provider`,
+          );
+        }
+      }
+    }
+
+    const disabled = cascadeDisabled(
+      this.plugins,
+      this.plugins.filter((plugin) => !this.enabled.has(plugin.id)).map((plugin) => plugin.id),
+    );
+    this.status = new Map();
+    for (const plugin of this.plugins) {
+      this.status.set(plugin.id, disabled.get(plugin.id) ?? 'enabled');
+    }
+
+    const effectiveEnabled = new Set(
+      this.plugins
+        .filter((plugin) => this.status.get(plugin.id) === 'enabled')
+        .map((plugin) => plugin.id),
+    );
+    const graph = resolvePluginGraph(this.plugins, effectiveEnabled);
+    this.loadOrder = graph.order;
+
+    this.capabilities = new CapabilityRegistry();
+    for (const plugin of this.loadOrder) {
+      for (const capability of plugin.manifest.provides) {
+        const factory = capabilityFactory(plugin, capability);
+        if (!factory) {
+          throw new Error(
+            `Plugin ${plugin.id} provides ${capability} but does not export a factory`,
+          );
+        }
+        this.capabilities.register(plugin.id, capability, factory);
+      }
+    }
+    for (const plugin of this.plugins) {
+      this.capabilities.setPluginEnabled(plugin.id, this.status.get(plugin.id) === 'enabled');
+    }
+  }
+
+  async #runLifecycle(plugin, name) {
+    const hook = plugin.manifest.lifecycle?.[name];
+    if (!hook) return;
+    const fn =
+      typeof hook === 'function' ? hook : (plugin.module[hook] ?? plugin.module.default?.[hook]);
+    if (typeof fn !== 'function') {
+      throw new Error(`Plugin ${plugin.id} lifecycle.${name} does not resolve to a function`);
+    }
+    await fn({ plugin, manager: this });
+  }
+}
+
+async function createPluginManager(config, options) {
+  const manager = new PluginManager(config, options);
+  await manager.init();
+  return manager;
+}
+
+export { PluginManager, createPluginManager };