arcway 0.1.27 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",

package/server/boot/index.js

@@ -18,6 +18,7 @@ import { runHook } from './hooks.js';
 import { createViteDevRouter } from '../pages/vite-dev.js';
 import { resolvePagesOutDir } from '../pages/out-dir.js';
 import { collectRuntimeMeta } from '../meta.js';
+import { createPluginManager } from '../plugins/manager.js';
 import path from 'node:path';
 
 async function boot(options) {
@@ -27,6 +28,9 @@ async function boot(options) {
   const envFiles = loadEnvFiles(rootDir, mode);
   const config = await makeConfig(rootDir, { overrides: options.configOverrides, mode });
 
+  const plugins = await createPluginManager(config.plugins, { runLifecycle: false });
+  config.database.pluginMigrations = plugins.migrations();
+
   const infrastructure = await createInfrastructure(config, { runMigrations: true });
   const { db, redis, queue, cache, files, mail, events, log } = infrastructure;
   const meta = await collectRuntimeMeta(rootDir);
@@ -42,6 +46,11 @@ async function boot(options) {
   // because downstream consumers read properties off this reference at use time.
   const appContext = { db, redis, events, queue, cache, files, mail, log, fileWatcher, meta };
 
+  plugins.log = log;
+  appContext.plugins = plugins;
+
+  await plugins.runEnabledLifecycle();
+
   await runHook('init', appContext, rootDir);
 
   const mcpRouter = new McpRouter(config.mcp, { log });
@@ -75,6 +84,7 @@ async function boot(options) {
     log,
     meta,
     workerPool,
+    plugins,
   });
   await jobRunner.init();
 

package/server/build.js

@@ -12,6 +12,7 @@ import { discoverMiddleware } from './router/middleware.js';
 import { EventHandler } from './events/handler.js';
 import { discoverJobs } from './jobs/runner.js';
 import { collectRuntimeMeta } from './meta.js';
+import { createPluginManager } from './plugins/manager.js';
 
 async function writeBuildMeta(rootDir, meta) {
   const buildDir = path.join(rootDir, '.build');
@@ -23,9 +24,11 @@ async function writeBuildMeta(rootDir, meta) {
 }
 
 async function validateServerModules(config) {
+  const plugins = await createPluginManager(config.plugins, { runLifecycle: false });
   if (config?.api?.enabled !== false && config?.api?.dir) {
     await discoverRoutes(config.api.dir);
     await discoverMiddleware(config.api.dir);
+    await plugins.discoverRoutes();
   }
 
   if (config?.events?.dir) {
@@ -33,7 +36,14 @@ async function validateServerModules(config) {
       { dir: config.events.dir },
       {
         events: { subscribe() {} },
-        log: { info() {}, warn() {}, error() {}, extend() { return this; } },
+        log: {
+          info() {},
+          warn() {},
+          error() {},
+          extend() {
+            return this;
+          },
+        },
       },
     );
     await handler.init();
@@ -41,6 +51,7 @@ async function validateServerModules(config) {
 
   if (config?.jobs?.enabled !== false && config?.jobs?.dir) {
     await discoverJobs(config.jobs.dir);
+    await plugins.discoverJobs();
   }
 }
 

package/server/config/loader.js

@@ -12,12 +12,14 @@ import resolveRedis from './modules/redis.js';
 import resolveCache from './modules/cache.js';
 import resolveEvents from './modules/events.js';
 import resolveMail from './modules/mail.js';
+import resolveSecrets from './modules/secrets.js';
 import resolveSession from './modules/session.js';
 import resolvePages from './modules/pages.js';
 import resolveBuild from './modules/build.js';
 import resolveMcp from './modules/mcp.js';
 import resolveWebsocket from './modules/websocket.js';
 import resolveSeeds from './modules/seeds.js';
+import resolvePlugins from './modules/plugins.js';
 
 function deepMerge(target, source) {
   const result = { ...target };
@@ -49,12 +51,14 @@ const modules = [
   resolveFiles,
   resolveMail,
   resolveRedis,
+  resolveSecrets,
   resolveSession,
   resolvePages,
   resolveBuild,
   resolveMcp,
   resolveWebsocket,
   resolveSeeds,
+  resolvePlugins,
 ];
 
 async function makeConfig(rootDir, { overrides, mode } = {}) {

package/server/config/modules/mcp.js

@@ -3,7 +3,11 @@ const DEFAULTS = {
 };
 
 function resolve(config) {
-  return { ...config, mcp: { ...DEFAULTS, ...config.mcp } };
+  const mcp = { ...DEFAULTS, ...config.mcp };
+  if (!mcp.secret && config.secrets?.values?.['mcp-api']) {
+    mcp.secret = config.secrets.values['mcp-api'];
+  }
+  return { ...config, mcp };
 }
 
 export default resolve;

package/server/config/modules/plugins.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+
+const DEFAULTS = {
+  enabled: false,
+  dirs: ['plugins'],
+};
+
+function resolve(config, { rootDir } = {}) {
+  const plugins = { ...DEFAULTS, ...config.plugins };
+  const dirs = Array.isArray(plugins.dirs) ? plugins.dirs : [plugins.dirs];
+  plugins.dirs = dirs
+    .filter((dir) => typeof dir === 'string' && dir.length > 0)
+    .map((dir) => (rootDir && !path.isAbsolute(dir) ? path.resolve(rootDir, dir) : dir));
+  plugins.enabled = plugins.enabled === true;
+  return { ...config, plugins };
+}
+
+export default resolve;

package/server/config/modules/secrets.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  deriveInfraSecrets,
+  encodeMasterSecret,
+  normalizeMasterSecret,
+  validateVaultKey,
+} from '../../lib/vault/secrets.js';
+
+const DEFAULT_KEY_FILE = '.build/arcway-master-secret.key';
+
+const EXPLICIT_ENV = Object.freeze({
+  session: 'SESSION_SECRET',
+  'plugin-vault': 'PLUGIN_VAULT_KEY',
+  'mcp-api': 'MCP_API_KEY',
+  'pty-api': 'PTY_API_KEY',
+  'pty-server-api': 'PTY_SERVER_API_KEY',
+});
+
+function isProduction(mode) {
+  return mode === 'production';
+}
+
+function readKeyFile(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if ((stat.mode & 0o077) !== 0) {
+      throw new Error('Arcway master secret keyfile permissions must be 0600');
+    }
+    return fs.readFileSync(filePath, 'utf8').trim();
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function createDevKeyFile(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const encoded = encodeMasterSecret();
+
+  try {
+    const fd = fs.openSync(
+      filePath,
+      fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY,
+      0o600,
+    );
+    try {
+      fs.writeFileSync(fd, `${encoded}\n`, 'utf8');
+    } finally {
+      fs.closeSync(fd);
+    }
+    return encoded;
+  } catch (error) {
+    if (error.code === 'EEXIST') return readKeyFile(filePath);
+    throw error;
+  }
+}
+
+function loadMasterSecret(rawSecrets, { rootDir, mode, env }) {
+  const configured = rawSecrets.master ?? env.ARCWAY_MASTER_SECRET;
+  if (configured) return { value: configured, source: 'config' };
+
+  if (isProduction(mode)) {
+    throw new Error(
+      'ARCWAY_MASTER_SECRET is required when arcway.config secrets are enabled in production',
+    );
+  }
+
+  const keyFile = path.resolve(rootDir, rawSecrets.keyFile ?? DEFAULT_KEY_FILE);
+  const existing = readKeyFile(keyFile);
+  if (existing) return { value: existing, source: 'keyfile', keyFile };
+
+  return { value: createDevKeyFile(keyFile), source: 'generated-keyfile', keyFile };
+}
+
+function explicitValue(name, rawSecrets, env) {
+  const explicit = rawSecrets.explicit?.[name];
+  if (explicit !== undefined && explicit !== null && explicit !== '') return explicit;
+
+  const envName = EXPLICIT_ENV[name];
+  const fromEnv = envName ? env[envName] : undefined;
+  return fromEnv || undefined;
+}
+
+function validateExplicit(name, value) {
+  if (name === 'plugin-vault') return validateVaultKey(value);
+  return String(value);
+}
+
+function resolve(config, { rootDir, mode } = {}) {
+  if (!config.secrets) return config;
+
+  const env = config.secrets.env ?? process.env;
+  const rawSecrets = config.secrets;
+  const master = loadMasterSecret(rawSecrets, { rootDir, mode, env });
+  normalizeMasterSecret(master.value);
+
+  const derived = deriveInfraSecrets(master.value);
+  const values = { ...derived };
+  const explicit = {};
+  const previousValues = {};
+
+  const previousMaster = rawSecrets.previous ?? env.ARCWAY_MASTER_SECRET_PREVIOUS;
+  if (previousMaster) {
+    normalizeMasterSecret(previousMaster, 'Previous Arcway master secret');
+    Object.assign(previousValues, deriveInfraSecrets(previousMaster));
+  }
+
+  for (const name of Object.keys(EXPLICIT_ENV)) {
+    const value = explicitValue(name, rawSecrets, env);
+    if (!value) continue;
+
+    explicit[name] = validateExplicit(name, value);
+    values[name] = explicit[name];
+    if (derived[name] !== explicit[name]) {
+      previousValues[name] = explicit[name];
+    }
+  }
+
+  const vapidPublic = rawSecrets.explicit?.vapidPublic ?? env.VAPID_PUBLIC_KEY;
+  const vapidPrivate = rawSecrets.explicit?.vapidPrivate ?? env.VAPID_PRIVATE_KEY;
+  if (vapidPublic || vapidPrivate) {
+    if (!vapidPublic || !vapidPrivate) {
+      throw new Error('VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY must be provided together');
+    }
+    explicit.vapid = { publicKey: String(vapidPublic), privateKey: String(vapidPrivate) };
+    values.vapid = explicit.vapid;
+    previousValues.vapid = explicit.vapid;
+  }
+
+  return {
+    ...config,
+    secrets: {
+      enabled: true,
+      keyFile: master.keyFile,
+      source: master.source,
+      values,
+      derived,
+      explicit,
+      previousValues,
+    },
+  };
+}
+
+export default resolve;

package/server/config/modules/session.js

@@ -2,7 +2,11 @@ import { resolveSessionConfig } from '../../session/index.js';
 
 function resolve(config, { mode } = {}) {
   if (!config.session) return config;
-  const session = resolveSessionConfig(config.session, mode);
+  const sessionInput = {
+    ...config.session,
+    password: config.session.password || config.secrets?.values?.session,
+  };
+  const session = resolveSessionConfig(sessionInput, mode);
   return { ...config, session };
 }
 

package/server/db/index.js

@@ -6,18 +6,39 @@ import { loadModule } from '../module-loader.js';
 import { introspectSchema, generateSchemaMarkdown } from './schema/index.js';
 
 class MigrationSource {
-  constructor(directory) {
+  constructor(directory, pluginMigrations = []) {
     this.directory = directory;
+    this.pluginMigrations = pluginMigrations;
+    this.migrationPaths = new Map();
   }
   async getMigrations() {
-    const files = await discoverFiles(this.directory, { skipUnderscore: false });
-    return files.map((f) => f.name);
+    this.migrationPaths.clear();
+    const migrations = [];
+
+    if (this.directory) {
+      const files = await discoverFiles(this.directory, { skipUnderscore: false });
+      for (const file of files) {
+        migrations.push(file.name);
+        this.migrationPaths.set(file.name, file.filePath);
+      }
+    }
+
+    for (const plugin of this.pluginMigrations ?? []) {
+      const files = await discoverFiles(plugin.dir, { skipUnderscore: false });
+      for (const file of files) {
+        const name = `plugins/${plugin.pluginId}/${file.name}`;
+        migrations.push(name);
+        this.migrationPaths.set(name, file.filePath);
+      }
+    }
+
+    return migrations;
   }
   getMigrationName(migration) {
     return migration;
   }
   async getMigration(migration) {
-    const filePath = path.resolve(this.directory, migration);
+    const filePath = this.migrationPaths.get(migration) ?? path.resolve(this.directory, migration);
     return loadModule(filePath, import.meta.url);
   }
 }
@@ -77,9 +98,10 @@ async function createDB(config, { log } = {}) {
 
   db.runMigrations = async () => {
     const migrationsDir = config.dir;
-    if (!migrationsDir) return;
+    const pluginMigrations = config.pluginMigrations ?? [];
+    if (!migrationsDir && pluginMigrations.length === 0) return;
     const [batch, migrations] = await db.migrate.latest({
-      migrationSource: new MigrationSource(migrationsDir),
+      migrationSource: new MigrationSource(migrationsDir, pluginMigrations),
     });
     if (migrations.length > 0) {
       log?.info(`Migrations (batch ${batch}): ${migrations.join(', ')}`);
@@ -90,9 +112,12 @@ async function createDB(config, { log } = {}) {
 
   db.runRollback = async () => {
     const migrationsDir = config.dir;
-    if (!migrationsDir) throw new Error('No migrations dir configured');
+    const pluginMigrations = config.pluginMigrations ?? [];
+    if (!migrationsDir && pluginMigrations.length === 0) {
+      throw new Error('No migrations dir configured');
+    }
     const [batch, entries] = await db.migrate.rollback({
-      migrationSource: new MigrationSource(migrationsDir),
+      migrationSource: new MigrationSource(migrationsDir, pluginMigrations),
     });
     return { batch, log: entries };
   };

package/server/discovery.js

@@ -8,7 +8,10 @@ import { loadModule } from './module-loader.js';
  * Skips files starting with underscore by default.
  * Returns sorted array of { name, filePath, relativePath }.
  */
-async function discoverFiles(dir, { recursive = false, extensions = ['.js'], skipUnderscore = true, filter } = {}) {
+async function discoverFiles(
+  dir,
+  { recursive = false, extensions = ['.js'], skipUnderscore = true, filter } = {},
+) {
   if (!dir) return [];
 
   let files;
@@ -49,7 +52,10 @@ async function discoverFiles(dir, { recursive = false, extensions = ['.js'], ski
  * Returns sorted array of { name, filePath, relativePath, module }.
  * Throws with a descriptive message if any file fails to import.
  */
-async function discoverModules(dir, { recursive = false, extensions = ['.js'], skipUnderscore = true, filter, label = 'file' } = {}) {
+async function discoverModules(
+  dir,
+  { recursive = false, extensions = ['.js'], skipUnderscore = true, filter, label = 'file' } = {},
+) {
   const files = await discoverFiles(dir, { recursive, extensions, skipUnderscore, filter });
   const results = [];
   for (const entry of files) {
@@ -64,4 +70,40 @@ async function discoverModules(dir, { recursive = false, extensions = ['.js'], s
   return results;
 }
 
-export { discoverFiles, discoverModules };
+async function discoverPackageDirectories(
+  dir,
+  { markerFiles = ['package.json'], label = 'package' } = {},
+) {
+  if (!dir) return [];
+
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+
+  const packages = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('_')) continue;
+    const packageDir = path.join(dir, entry.name);
+    const hasMarker = await Promise.all(
+      markerFiles.map(async (marker) => {
+        try {
+          await fs.access(path.join(packageDir, marker));
+          return true;
+        } catch (err) {
+          if (err.code === 'ENOENT') return false;
+          throw err;
+        }
+      }),
+    );
+    if (!hasMarker.some(Boolean)) continue;
+    packages.push({ name: entry.name, dir: packageDir, label });
+  }
+  packages.sort((a, b) => a.name.localeCompare(b.name));
+  return packages;
+}
+
+export { discoverFiles, discoverModules, discoverPackageDirectories };

package/server/index.js

@@ -1,6 +1,8 @@
 export { type } from 'arktype';
 export { buildContext } from './context.js';
 export { default as boot } from './boot.js';
+export { CapabilityNotAvailable, CapabilityRegistry } from './plugins/capabilities.js';
+export { PluginManager, createPluginManager } from './plugins/manager.js';
 export {
   Arcway,
   Solo,

package/server/internals.js

@@ -42,6 +42,9 @@ import { createRateLimitMiddleware } from './rate-limit/index.js';
 import { createHttpServer, listen, closeServer } from './server.js';
 import { startWatcher } from './watcher.js';
 import { build } from './build.js';
+import { CapabilityNotAvailable, CapabilityRegistry } from './plugins/capabilities.js';
+import { discoverPlugins } from './plugins/discovery.js';
+import { PluginManager, createPluginManager } from './plugins/manager.js';
 import {
   discoverPages,
   discoverLayouts,
@@ -68,6 +71,8 @@ import { attachGraphQLSubscriptions } from './graphql/subscriptions.js';
 export {
   ApiRouter,
   Cache,
+  CapabilityNotAvailable,
+  CapabilityRegistry,
   makeConfig,
   Files,
   KnexQueueDriver,
@@ -101,9 +106,11 @@ export {
   createLoaderFactory,
   createPagesHandler,
   createPagesWatcher,
+  createPluginManager,
   createRateLimitMiddleware,
   createWebSocketServer,
   discoverJobs,
+  discoverPlugins,
   EventHandler,
   discoverErrorPages,
   discoverGraphQL,
@@ -127,6 +134,7 @@ export {
   mergeWebSocketHandlers,
   parseCron,
   patternToFileName,
+  PluginManager,
   resolveLayoutChain,
   resolveSessionConfig,
   runSeeds,

package/server/jobs/drivers/run-handler.js

@@ -16,6 +16,9 @@ async function runHandler(reg, payload, workerPool) {
     return;
   }
   const ctx = buildContext(reg.store, { payload });
+  if (reg.definition.plugin) {
+    reg.store.plugins?.injectCapabilities(ctx, reg.definition.plugin.requires);
+  }
   await reg.definition.handler(ctx);
 }
 

package/server/jobs/runner.js

@@ -1,4 +1,3 @@
-import path from 'node:path';
 import { discoverModules } from '../discovery.js';
 import { buildContext } from '../context.js';
 import { parseCron, matchesCron } from './cron.js';
@@ -45,7 +44,10 @@ class JobRunner {
   _stopped = false;
   _lastEnqueuedMinute = new Map();
 
-  constructor(config, { db, queue, cache, files, mail, events, log, meta, workerPool } = {}) {
+  constructor(
+    config,
+    { db, queue, cache, files, mail, events, log, meta, workerPool, plugins } = {},
+  ) {
     this._config = config;
     this._log = log;
     this._dispatcher = new JobDispatcher({
@@ -53,7 +55,7 @@ class JobRunner {
       staleTimeoutMs: config?.staleTimeoutMs,
       workerPool,
     });
-    this._appContext = { db, queue, cache, files, mail, events, log, meta };
+    this._appContext = { db, queue, cache, files, mail, events, log, meta, plugins };
   }
 
   get dispatcher() {
@@ -75,13 +77,15 @@ class JobRunner {
     // Discover and register user jobs. `filePath` is captured so the
     // dispatcher can dynamic-import the handler inside a worker thread.
     const discovered = await discoverJobs(jobsDir);
-    for (const { definition, fileName, filePath } of discovered) {
+    const pluginJobs = (await this._appContext.plugins?.discoverJobs?.()) ?? [];
+    for (const { definition, fileName, filePath } of [...discovered, ...pluginJobs]) {
       this._dispatcher.register('app', definition, this._appContext, filePath);
       this._jobs.push({
         jobName: definition.name,
         fileName,
         schedule: definition.schedule,
         handler: definition.handler,
+        plugin: definition.plugin,
         cooldownMs: definition.cooldownMs,
         staleTimeout: definition.staleTimeout,
       });
@@ -110,6 +114,7 @@ class JobRunner {
         this._continuousJobs.push({
           qualifiedName: `app/${job.jobName}`,
           handler: job.handler,
+          plugin: job.plugin,
           cooldownMs: job.cooldownMs,
           appContext: this._appContext,
         });
@@ -192,6 +197,9 @@ class JobRunner {
       try {
         const start = Date.now();
         const ctx = buildContext(entry.appContext, { payload: void 0 });
+        if (entry.plugin) {
+          entry.appContext.plugins?.injectCapabilities(ctx, entry.plugin.requires);
+        }
         await entry.handler(ctx);
         consecutiveErrors = 0;
         const elapsed = Date.now() - start;

package/server/lib/vault/index.js

@@ -2,13 +2,33 @@ import { hashPassword, verifyPassword } from './password.js';
 import { generateUUID, generateNanoId } from './ids.js';
 import { encrypt, decrypt } from './encrypt.js';
 import { jwtEncode, jwtDecode } from './jwt.js';
+import {
+  decryptWithRotation,
+  deriveBytes,
+  deriveInfraSecret,
+  deriveInfraSecrets,
+  deriveVapidKeyPair,
+  encodeMasterSecret,
+  formatVaultKey,
+  normalizeMasterSecret,
+  validateVaultKey,
+} from './secrets.js';
 export {
+  decryptWithRotation,
   decrypt,
+  deriveBytes,
+  deriveInfraSecret,
+  deriveInfraSecrets,
+  deriveVapidKeyPair,
+  encodeMasterSecret,
   encrypt,
+  formatVaultKey,
   generateNanoId,
   generateUUID,
   hashPassword,
   jwtDecode,
   jwtEncode,
+  normalizeMasterSecret,
+  validateVaultKey,
   verifyPassword,
 };