arcway 0.1.29 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.29",
+  "version": "0.2.0",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -137,5 +137,12 @@
     "react-dom": "^19.2.4",
     "storybook": "^10.2.8",
     "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild",
+      "sharp"
+    ]
   }
 }

package/server/bin/cli.js

@@ -12,6 +12,7 @@ import registerGraphQLSchema from './commands/graphql-schema.js';
 import registerSchema from './commands/schema.js';
 import registerMigrate from './commands/migrate.js';
 import registerBootstrap from './commands/bootstrap.js';
+import registerVault from './commands/vault.js';
 
 function getPackageVersion() {
   try {
@@ -38,6 +39,7 @@ function createProgram() {
   registerSchema(program);
   registerMigrate(program);
   registerBootstrap(program);
+  registerVault(program);
   return program;
 }
 

package/server/bin/commands/bootstrap.js

@@ -1,23 +1,28 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { encodeMasterSecret } from '../../lib/vault/index.js';
 
-const FILES = {
-  'arcway.config.js': `export default {
+function createFiles(masterSecret) {
+  return {
+    'arcway.config.js': `export default {
   database: {
     client: 'better-sqlite3',
     connection: { filename: './data.db' },
   },
+  vault: {
+    masterSecret: process.env.ARCWAY_MASTER_SECRET,
+  },
 };
 `,
 
-  'api/index.js': `export const GET = {
+    'api/index.js': `export const GET = {
   handler: async (ctx) => {
     return { data: { message: 'Hello from Arcway!' } };
   },
 };
 `,
 
-  'api/users/index.js': `export const GET = {
+    'api/users/index.js': `export const GET = {
   handler: async (ctx) => {
     const { db } = ctx;
     const users = await db('users').select('*');
@@ -38,7 +43,7 @@ export const POST = {
 };
 `,
 
-  'api/users/[id].js': `export const GET = {
+    'api/users/[id].js': `export const GET = {
   handler: async (ctx) => {
     const { req, db } = ctx;
     const user = await db('users').where('id', req.query.id).first();
@@ -48,13 +53,13 @@ export const POST = {
 };
 `,
 
-  'listeners/users/created.js': `export default async (ctx) => {
+    'listeners/users/created.js': `export default async (ctx) => {
   const { event, log } = ctx;
   log.info('New user created', { userId: event.payload.id });
 };
 `,
 
-  'jobs/cleanup-sessions.js': `export default {
+    'jobs/cleanup-sessions.js': `export default {
   schedule: '0 3 * * *', // Every day at 3 AM
   handler: async (ctx) => {
     const { db, log } = ctx;
@@ -66,7 +71,7 @@ export const POST = {
 };
 `,
 
-  'migrations/202601010000-create-users.js': `export async function up(knex) {
+    'migrations/202601010000-create-users.js': `export async function up(knex) {
   await knex.schema.createTable('users', (table) => {
     table.increments('id').primary();
     table.string('name').notNullable();
@@ -80,7 +85,7 @@ export async function down(knex) {
 }
 `,
 
-  'pages/index.jsx': `export default function Home() {
+    'pages/index.jsx': `export default function Home() {
   return (
     <div style={{ padding: '2rem', fontFamily: 'system-ui' }}>
       <h1>Welcome to Arcway</h1>
@@ -90,23 +95,25 @@ export async function down(knex) {
 }
 `,
 
-  '.env': `# NODE_ENV=development
-# SESSION_PASSWORD=change-me-to-a-random-32-char-string
+    '.env': `# NODE_ENV=development
+ARCWAY_MASTER_SECRET=${masterSecret}
 `,
 
-  '.gitignore': `node_modules/
+    '.gitignore': `node_modules/
 .build/
 data.db
 .env.local
 .env.*.local
 `,
-};
+  };
+}
 
 function bootstrap(rootDir) {
+  const files = createFiles(encodeMasterSecret());
   let created = 0;
   let skipped = 0;
 
-  for (const [relativePath, content] of Object.entries(FILES)) {
+  for (const [relativePath, content] of Object.entries(files)) {
     const fullPath = join(rootDir, relativePath);
     if (existsSync(fullPath)) {
       console.log(`  skip  ${relativePath} (already exists)`);

package/server/bin/commands/vault.js

@@ -0,0 +1,14 @@
+import { encodeMasterSecret } from '../../lib/vault/index.js';
+
+function registerVault(program) {
+  const vault = program.command('vault').description('Vault utilities');
+
+  vault
+    .command('generate-key')
+    .description('Generate a new Arcway master secret')
+    .action(() => {
+      console.log(encodeMasterSecret());
+    });
+}
+
+export default registerVault;

package/server/boot/index.js

@@ -29,7 +29,6 @@ async function boot(options) {
   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;
@@ -44,7 +43,19 @@ async function boot(options) {
   // framework services and to the init/ready/shutdown hooks. Mutations from
   // the init hook (e.g. wrapping `appContext.db`) persist for process lifetime
   // because downstream consumers read properties off this reference at use time.
-  const appContext = { db, redis, events, queue, cache, files, mail, log, fileWatcher, meta };
+  const appContext = {
+    db,
+    redis,
+    events,
+    queue,
+    cache,
+    files,
+    mail,
+    log,
+    fileWatcher,
+    meta,
+    vault: config.vault,
+  };
 
   plugins.log = log;
   appContext.plugins = plugins;
@@ -83,6 +94,7 @@ async function boot(options) {
     events,
     log,
     meta,
+    vault: config.vault,
     workerPool,
     plugins,
   });

package/server/config/loader.js

@@ -12,7 +12,7 @@ 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 resolveVault from './modules/vault.js';
 import resolveSession from './modules/session.js';
 import resolvePages from './modules/pages.js';
 import resolveBuild from './modules/build.js';
@@ -51,7 +51,7 @@ const modules = [
   resolveFiles,
   resolveMail,
   resolveRedis,
-  resolveSecrets,
+  resolveVault,
   resolveSession,
   resolvePages,
   resolveBuild,

package/server/config/modules/mcp.js

@@ -4,8 +4,8 @@ const DEFAULTS = {
 
 function resolve(config) {
   const mcp = { ...DEFAULTS, ...config.mcp };
-  if (!mcp.secret && config.secrets?.values?.['mcp-api']) {
-    mcp.secret = config.secrets.values['mcp-api'];
+  if (!mcp.secret && config.vault?.values?.['mcp-api']) {
+    mcp.secret = config.vault.values['mcp-api'];
   }
   return { ...config, mcp };
 }

package/server/config/modules/session.js

@@ -2,9 +2,15 @@ import { resolveSessionConfig } from '../../session/index.js';
 
 function resolve(config, { mode } = {}) {
   if (!config.session) return config;
+  const vaultSession = config.vault?.values?.session;
+  const sessionKeyring = config.vault?.keyring?.map((entry) => ({
+    id: entry.id,
+    password: entry.secrets.session,
+  }));
   const sessionInput = {
     ...config.session,
-    password: config.session.password || config.secrets?.values?.session,
+    password: vaultSession,
+    keyring: sessionKeyring,
   };
   const session = resolveSessionConfig(sessionInput, mode);
   return { ...config, session };

package/server/config/modules/vault.js

@@ -0,0 +1,44 @@
+import {
+  deriveInfraSecretRing,
+  deriveInfraSecrets,
+  normalizeMasterSecretRing,
+} from '../../lib/vault/secrets.js';
+
+function loadMasterSecret(rawVault) {
+  if (rawVault.masterSecret !== undefined && rawVault.masterSecret !== null) {
+    return { value: rawVault.masterSecret, source: 'config' };
+  }
+
+  throw new Error(
+    'vault.masterSecret is required when Arcway vault is enabled. Generate one with `npx arcway vault generate-key`.',
+  );
+}
+
+function resolve(config) {
+  if (!config.vault) return config;
+
+  const rawVault = config.vault;
+  const master = loadMasterSecret(rawVault);
+  normalizeMasterSecretRing(master.value);
+
+  const ring = deriveInfraSecretRing(master.value);
+  const derived = deriveInfraSecrets(
+    Array.isArray(master.value) ? master.value.at(-1) : master.value,
+  );
+  const values = ring.active.secrets;
+
+  return {
+    ...config,
+    vault: {
+      enabled: true,
+      masterSecret: Array.isArray(master.value) ? master.value.at(-1) : master.value,
+      source: master.source,
+      values,
+      derived,
+      keyring: ring.entries,
+      activeKey: ring.active,
+    },
+  };
+}
+
+export default resolve;

package/server/context.js

@@ -2,15 +2,26 @@ import * as vault from './lib/vault/index.js';
 import { wsBroadcastToPath, wsSendToSocket } from './ws/registry.js';
 
 function trackDb(db) {
-  if (!db || typeof db !== 'function' && typeof db !== 'object') return { db, stats: { queries: 0, durationMs: 0 } };
+  if (!db || (typeof db !== 'function' && typeof db !== 'object'))
+    return { db, stats: { queries: 0, durationMs: 0 } };
   const stats = { queries: 0, durationMs: 0 };
   const handler = {
     get(target, prop, receiver) {
       const value = Reflect.get(target, prop, receiver);
       if (typeof value !== 'function') return value;
-      if (prop === 'raw' || prop === 'select' || prop === 'insert' || prop === 'update' ||
-          prop === 'delete' || prop === 'del' || prop === 'from' || prop === 'into' ||
-          prop === 'table' || prop === 'with' || prop === 'withRecursive') {
+      if (
+        prop === 'raw' ||
+        prop === 'select' ||
+        prop === 'insert' ||
+        prop === 'update' ||
+        prop === 'delete' ||
+        prop === 'del' ||
+        prop === 'from' ||
+        prop === 'into' ||
+        prop === 'table' ||
+        prop === 'with' ||
+        prop === 'withRecursive'
+      ) {
         return (...args) => {
           const builder = value.apply(target, args);
           return wrapBuilder(builder, stats);
@@ -101,6 +112,16 @@ function normalizeMeta(meta) {
   };
 }
 
+function buildVaultToolkit(vaultConfig) {
+  if (!vaultConfig?.masterSecret) return vault;
+
+  return {
+    ...vault,
+    deriveKey: (label) => vault.deriveKey(vaultConfig.masterSecret, label),
+    deriveKeyPair: (label, opts) => vault.deriveKeyPair(vaultConfig.masterSecret, label, opts),
+  };
+}
+
 function buildContext(appContext, extras) {
   const tracked = trackDb(appContext.db);
   const normalizedExtras = { ...extras };
@@ -124,12 +145,13 @@ function buildContext(appContext, extras) {
     files: appContext.files,
     mail: appContext.mail,
     meta: normalizeMeta(appContext.meta),
-    vault,
+    vault: buildVaultToolkit(appContext.vault),
     ws,
     err: (input, status) => buildErrResponse(input, status),
     _dbStats: tracked.stats,
     ...normalizedExtras,
   };
+  ctx.plugins = appContext.plugins?.buildContextProxy?.(ctx);
   return ctx;
 }
 

package/server/db/index.js

@@ -6,9 +6,8 @@ import { loadModule } from '../module-loader.js';
 import { introspectSchema, generateSchemaMarkdown } from './schema/index.js';
 
 class MigrationSource {
-  constructor(directory, pluginMigrations = []) {
+  constructor(directory) {
     this.directory = directory;
-    this.pluginMigrations = pluginMigrations;
     this.migrationPaths = new Map();
   }
   async getMigrations() {
@@ -23,15 +22,6 @@ class MigrationSource {
       }
     }
 
-    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) {
@@ -98,10 +88,9 @@ async function createDB(config, { log } = {}) {
 
   db.runMigrations = async () => {
     const migrationsDir = config.dir;
-    const pluginMigrations = config.pluginMigrations ?? [];
-    if (!migrationsDir && pluginMigrations.length === 0) return;
+    if (!migrationsDir) return;
     const [batch, migrations] = await db.migrate.latest({
-      migrationSource: new MigrationSource(migrationsDir, pluginMigrations),
+      migrationSource: new MigrationSource(migrationsDir),
     });
     if (migrations.length > 0) {
       log?.info(`Migrations (batch ${batch}): ${migrations.join(', ')}`);
@@ -112,12 +101,11 @@ async function createDB(config, { log } = {}) {
 
   db.runRollback = async () => {
     const migrationsDir = config.dir;
-    const pluginMigrations = config.pluginMigrations ?? [];
-    if (!migrationsDir && pluginMigrations.length === 0) {
+    if (!migrationsDir) {
       throw new Error('No migrations dir configured');
     }
     const [batch, entries] = await db.migrate.rollback({
-      migrationSource: new MigrationSource(migrationsDir, pluginMigrations),
+      migrationSource: new MigrationSource(migrationsDir),
     });
     return { batch, log: entries };
   };

package/server/jobs/runner.js

@@ -46,7 +46,7 @@ class JobRunner {
 
   constructor(
     config,
-    { db, queue, cache, files, mail, events, log, meta, workerPool, plugins } = {},
+    { db, queue, cache, files, mail, events, log, meta, vault, workerPool, plugins } = {},
   ) {
     this._config = config;
     this._log = log;
@@ -55,7 +55,7 @@ class JobRunner {
       staleTimeoutMs: config?.staleTimeoutMs,
       workerPool,
     });
-    this._appContext = { db, queue, cache, files, mail, events, log, meta, plugins };
+    this._appContext = { db, queue, cache, files, mail, events, log, meta, vault, plugins };
   }
 
   get dispatcher() {

package/server/jobs/worker-entry.js

@@ -17,13 +17,17 @@ if (!parentPort) {
 const moduleCache = new Map();
 let infrastructure = null;
 let infrastructurePromise = null;
+let resolvedConfig = null;
 let shuttingDown = false;
 
 async function ensureInfrastructure() {
   if (infrastructure) return infrastructure;
   if (!infrastructurePromise) {
     infrastructurePromise = resolveWorkerConfig(workerData)
-      .then((config) => createInfrastructure(config, { runMigrations: false }))
+      .then((config) => {
+        resolvedConfig = config;
+        return createInfrastructure(config, { runMigrations: false });
+      })
       .then((services) => {
         infrastructure = services;
         return services;
@@ -66,7 +70,10 @@ async function runTask(task) {
   // and any future cpu-only caller) gets the raw payload — no DB spin-up.
   if (withContext) {
     const services = await ensureInfrastructure();
-    const ctx = buildContext({ ...services, meta: workerData?.meta }, { payload });
+    const ctx = buildContext(
+      { ...services, meta: workerData?.meta, vault: resolvedConfig?.vault },
+      { payload },
+    );
     return fn(ctx);
   }
   return fn(payload);

package/server/lib/vault/index.js

@@ -4,22 +4,28 @@ import { encrypt, decrypt } from './encrypt.js';
 import { jwtEncode, jwtDecode } from './jwt.js';
 import {
   decryptWithRotation,
+  deriveKey,
+  deriveKeyPair,
   deriveBytes,
   deriveInfraSecret,
+  deriveInfraSecretRing,
   deriveInfraSecrets,
-  deriveVapidKeyPair,
   encodeMasterSecret,
   formatVaultKey,
   normalizeMasterSecret,
+  normalizeMasterSecretRing,
+  stableSessionPasswordId,
   validateVaultKey,
 } from './secrets.js';
 export {
   decryptWithRotation,
   decrypt,
+  deriveKey,
+  deriveKeyPair,
   deriveBytes,
   deriveInfraSecret,
+  deriveInfraSecretRing,
   deriveInfraSecrets,
-  deriveVapidKeyPair,
   encodeMasterSecret,
   encrypt,
   formatVaultKey,
@@ -29,6 +35,8 @@ export {
   jwtDecode,
   jwtEncode,
   normalizeMasterSecret,
+  normalizeMasterSecretRing,
+  stableSessionPasswordId,
   validateVaultKey,
   verifyPassword,
 };

package/server/lib/vault/secrets.js

@@ -1,18 +1,11 @@
-import { createECDH, hkdfSync, randomBytes } from 'node:crypto';
+import { createECDH, createHash, 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',
-]);
+const SECRET_NAMES = Object.freeze(['session', 'plugin-vault', 'mcp-api']);
 
 function base64Url(buffer) {
   return Buffer.from(buffer).toString('base64url');
@@ -65,6 +58,13 @@ function deriveBytes(master, namespace, length = MASTER_BYTES) {
   return Buffer.from(hkdfSync('sha256', key, HKDF_SALT, `arcway:${namespace}`, length));
 }
 
+function deriveKey(master, label) {
+  if (!label || typeof label !== 'string') {
+    throw new Error('deriveKey label must be a non-empty string');
+  }
+  return base64Url(deriveBytes(master, `app:${label}`, MASTER_BYTES));
+}
+
 function formatVaultKey(bytes) {
   const key = Buffer.from(bytes);
   if (key.length !== VAULT_KEY_BYTES) {
@@ -77,11 +77,15 @@ function validateVaultKey(value, label = 'plugin-vault secret') {
   return formatVaultKey(decodeVersionedSecret(value, label));
 }
 
-function deriveVapidKeyPair(master) {
+function deriveKeyPair(master, label, { curve = 'prime256v1' } = {}) {
+  if (!label || typeof label !== 'string') {
+    throw new Error('deriveKeyPair label must be a non-empty string');
+  }
+
   for (let i = 0; i < 32; i += 1) {
-    const privateKey = deriveBytes(master, `vapid:private:${i}`, 32);
+    const privateKey = deriveBytes(master, `keypair:${curve}:${label}:private:${i}`, 32);
     try {
-      const ecdh = createECDH('prime256v1');
+      const ecdh = createECDH(curve);
       ecdh.setPrivateKey(privateKey);
       return {
         publicKey: base64Url(ecdh.getPublicKey(null, 'uncompressed')),
@@ -91,16 +95,13 @@ function deriveVapidKeyPair(master) {
       // Try the next deterministic candidate.
     }
   }
-  throw new Error('Unable to derive a valid deterministic VAPID keypair');
+  throw new Error(`Unable to derive a valid deterministic ${curve} keypair for label "${label}"`);
 }
 
 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}`);
 }
 
@@ -112,6 +113,47 @@ function deriveInfraSecrets(master) {
   return values;
 }
 
+function normalizeMasterSecretRing(master) {
+  const masters = Array.isArray(master) ? master : [master];
+  const normalized = masters.filter(
+    (value) => value !== undefined && value !== null && value !== '',
+  );
+  if (normalized.length === 0) throw new Error('Arcway master secret keyring cannot be empty');
+  return normalized.map((value, index) =>
+    normalizeMasterSecret(value, `Arcway master secret keyring entry ${index + 1}`),
+  );
+}
+
+function stableSessionPasswordId(sessionSecret) {
+  const digest = createHash('sha256').update(`arcway:session-key-id:v1:${sessionSecret}`).digest();
+  const id = digest.readUIntBE(0, 6);
+  return String(id === 0 ? 1 : id);
+}
+
+function deriveInfraSecretRing(master) {
+  const masters = normalizeMasterSecretRing(master);
+  const entries = masters.map((value) => {
+    const secrets = deriveInfraSecrets(value);
+    return {
+      id: stableSessionPasswordId(secrets.session),
+      secrets,
+    };
+  });
+
+  const seenIds = new Set();
+  for (const entry of entries) {
+    if (seenIds.has(entry.id)) {
+      throw new Error('Derived session key ids collided; rotate with different master secrets');
+    }
+    seenIds.add(entry.id);
+  }
+
+  return {
+    entries,
+    active: entries.at(-1),
+  };
+}
+
 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');
@@ -138,12 +180,16 @@ function decryptWithRotation(ciphertext, { current, previous, decrypt, encrypt,
 export {
   SECRET_NAMES,
   decryptWithRotation,
+  deriveKey,
+  deriveKeyPair,
   deriveBytes,
   deriveInfraSecret,
+  deriveInfraSecretRing,
   deriveInfraSecrets,
-  deriveVapidKeyPair,
   encodeMasterSecret,
   formatVaultKey,
   normalizeMasterSecret,
+  normalizeMasterSecretRing,
+  stableSessionPasswordId,
   validateVaultKey,
 };

package/server/plugins/discovery.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { discoverPackageDirectories } from '../discovery.js';
+import { discoverModules, discoverPackageDirectories } from '../discovery.js';
 import { loadModule } from '../module-loader.js';
 import { validateManifest } from './manifest.js';
 
@@ -30,6 +30,36 @@ function getManifest(module, manifestPath) {
   return manifest;
 }
 
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must export an object`);
+  }
+}
+
+function getExports(module, exportsPath) {
+  const exported = module.default;
+  assertPlainObject(exported, `Plugin exports at ${exportsPath}`);
+  for (const [name, value] of Object.entries(exported)) {
+    if (typeof value !== 'function') {
+      throw new Error(`Plugin export ${name} at ${exportsPath} must be a function`);
+    }
+  }
+  return { ...exported };
+}
+
+// Load every `<dir>/<name>.js` and key the default export by file basename.
+// Used for the capabilities/ and hooks/ folder conventions.
+async function loadConventionModules(dir, label) {
+  if (!(await exists(dir))) return {};
+  const modules = await discoverModules(dir, { label: `plugin ${label}` });
+  const map = {};
+  for (const entry of modules) {
+    const name = path.basename(entry.name, path.extname(entry.name));
+    map[name] = entry.module.default ?? entry.module;
+  }
+  return map;
+}
+
 async function loadPluginPackage(packageDir) {
   const packageJsonPath = path.join(packageDir, 'package.json');
   if (!(await exists(packageJsonPath))) {
@@ -39,6 +69,7 @@ async function loadPluginPackage(packageDir) {
 
   const pluginJs = path.join(packageDir, 'plugin.js');
   const pluginJson = path.join(packageDir, 'plugin.json');
+  const exportsJs = path.join(packageDir, 'exports.js');
   let manifestPath;
   let module = {};
   let rawManifest;
@@ -50,14 +81,24 @@ async function loadPluginPackage(packageDir) {
   } else if (await exists(pluginJson)) {
     manifestPath = pluginJson;
     rawManifest = await readJson(pluginJson, 'plugin.json');
+  } else if (packageJson.arcway && typeof packageJson.arcway === 'object') {
+    // Metadata-only plugin: the manifest lives in package.json's "arcway" block,
+    // and code is discovered by folder convention (routes/, jobs/, capabilities/, hooks/).
+    manifestPath = packageJsonPath;
+    rawManifest = {};
   } else {
-    throw new Error(`Plugin package at ${packageDir} must include plugin.js or plugin.json`);
+    // A package without plugin.js/plugin.json and without an "arcway" block is
+    // not a plugin — skip it rather than failing discovery.
+    return null;
   }
 
+  // package.json "arcway" supplies the base metadata; an explicit plugin.js/plugin.json
+  // manifest (legacy) wins on conflict so existing plugins behave identically.
   const manifest = validateManifest(
     {
       version: packageJson.version,
       name: packageJson.name,
+      ...packageJson.arcway,
       ...rawManifest,
     },
     { packageName: packageJson.name },
@@ -65,10 +106,9 @@ async function loadPluginPackage(packageDir) {
 
   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');
+  const exportsModule = (await exists(exportsJs))
+    ? await loadModule(exportsJs, import.meta.url)
+    : null;
 
   return {
     id: manifest.id,
@@ -77,9 +117,11 @@ async function loadPluginPackage(packageDir) {
     manifest,
     module,
     manifestPath,
+    exports: exportsModule ? getExports(exportsModule, exportsJs) : {},
     routesDir: (await exists(routesDir)) ? routesDir : null,
     jobsDir: (await exists(jobsDir)) ? jobsDir : null,
-    migrationsDir: (await exists(migrationsDir)) ? migrationsDir : null,
+    capabilities: await loadConventionModules(path.join(packageDir, 'capabilities'), 'capability'),
+    hooks: await loadConventionModules(path.join(packageDir, 'hooks'), 'lifecycle hook'),
   };
 }
 
@@ -89,11 +131,12 @@ async function discoverPlugins(dirs) {
 
   for (const dir of dirs ?? []) {
     const packages = await discoverPackageDirectories(dir, {
-      markerFiles: ['plugin.js', 'plugin.json'],
+      markerFiles: ['package.json'],
       label: 'plugin',
     });
     for (const entry of packages) {
       const plugin = await loadPluginPackage(entry.dir);
+      if (!plugin) continue;
       if (seen.has(plugin.id)) {
         throw new Error(
           `Duplicate plugin id ${plugin.id} in ${seen.get(plugin.id)} and ${plugin.dir}`,

package/server/plugins/manager.js

@@ -14,17 +14,47 @@ function pluginEnabledByDefault(plugin, enablements) {
   if (Object.prototype.hasOwnProperty.call(enablements, plugin.id)) {
     return enablements[plugin.id] === true;
   }
-  return plugin.manifest.defaultEnabled === true;
+  return plugin.manifest.enabled !== false;
 }
 
 function capabilityFactory(plugin, capability) {
   return (
+    plugin.capabilities?.[capability] ??
     plugin.module.capabilities?.[capability] ??
     plugin.module.default?.capabilities?.[capability] ??
     plugin.module[`create${capability[0]?.toUpperCase() ?? ''}${capability.slice(1)}`]
   );
 }
 
+function bindPluginExports(plugin, ctx) {
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (typeof prop === 'symbol') return undefined;
+        if (prop === 'then') return undefined;
+
+        const fn = plugin.exports?.[prop];
+        if (!fn) {
+          throw new Error(`Plugin ${plugin.id} does not export function ${prop}`);
+        }
+        return (...args) => fn(ctx, ...args);
+      },
+      has(_target, prop) {
+        return typeof prop === 'string' && Object.hasOwn(plugin.exports ?? {}, prop);
+      },
+      ownKeys() {
+        return Object.keys(plugin.exports ?? {});
+      },
+      getOwnPropertyDescriptor(_target, prop) {
+        if (typeof prop !== 'string' || !Object.hasOwn(plugin.exports ?? {}, prop))
+          return undefined;
+        return { enumerable: true, configurable: true };
+      },
+    },
+  );
+}
+
 class PluginManager {
   constructor(config, { log, runLifecycle = true } = {}) {
     this.config = config ?? { enabled: false, dirs: [] };
@@ -96,12 +126,27 @@ class PluginManager {
     return this.capabilities.inject(ctx, requires);
   }
 
+  exportsFor(id, ctx) {
+    const plugin = this.getPlugin(id);
+    if (!plugin) throw new Error(`Unknown plugin: ${id}`);
+    if (this.status.get(plugin.id) !== 'enabled') {
+      throw new Error(`Plugin ${plugin.id} is not enabled`);
+    }
+    return bindPluginExports(plugin, ctx);
+  }
+
+  buildContextProxy(ctx) {
+    return {
+      get: (id) => this.exportsFor(id, ctx),
+    };
+  }
+
   async discoverRoutes() {
     const routes = [];
     for (const plugin of this.enabledPlugins) {
       if (!plugin.routesDir) continue;
       const discovered = await discoverRoutes(plugin.routesDir, {
-        prefix: `/plugins/${plugin.id}`,
+        prefix: `/_plugins/${plugin.id}`,
         plugin: {
           id: plugin.id,
           requires: plugin.manifest.requires,
@@ -132,16 +177,6 @@ class PluginManager {
     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) {
@@ -190,7 +225,7 @@ class PluginManager {
   }
 
   async #runLifecycle(plugin, name) {
-    const hook = plugin.manifest.lifecycle?.[name];
+    const hook = plugin.hooks?.[name] ?? plugin.manifest.lifecycle?.[name];
     if (!hook) return;
     const fn =
       typeof hook === 'function' ? hook : (plugin.module[hook] ?? plugin.module.default?.[hook]);

package/server/plugins/manifest.js

@@ -1,6 +1,4 @@
 const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
-const KINDS = new Set(['core', 'feature']);
-const SCOPES = new Set(['global', 'workspace']);
 
 function assertPlainObject(value, label) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -22,19 +20,6 @@ function normalizeRequires(value) {
   return { ...value };
 }
 
-function normalizeContributes(value) {
-  if (value === undefined) return {};
-  assertPlainObject(value, 'plugin contributes');
-  return {
-    ...value,
-    tools: value.tools ?? [],
-    routes: value.routes ?? [],
-    jobs: value.jobs ?? [],
-    migrations: value.migrations,
-    ui: value.ui,
-  };
-}
-
 function normalizeLifecycle(value) {
   if (value === undefined) return {};
   assertPlainObject(value, 'plugin lifecycle');
@@ -53,17 +38,34 @@ function normalizeLifecycle(value) {
 function validateManifest(rawManifest, { packageName } = {}) {
   assertPlainObject(rawManifest, 'plugin manifest');
 
+  if (rawManifest.enabled !== undefined && typeof rawManifest.enabled !== 'boolean') {
+    throw new Error('plugin enabled must be a boolean');
+  }
+
+  const { id, name, version, enabled, provides, requires, lifecycle } = rawManifest;
+  const appMetadata = { ...rawManifest };
+  for (const key of [
+    'id',
+    'name',
+    'version',
+    'defaultEnabled',
+    'enabled',
+    'provides',
+    'requires',
+    'lifecycle',
+  ]) {
+    delete appMetadata[key];
+  }
+
   const manifest = {
-    id: rawManifest.id ?? packageName,
-    name: rawManifest.name ?? rawManifest.id ?? packageName,
-    version: rawManifest.version,
-    kind: rawManifest.kind ?? 'feature',
-    scope: rawManifest.scope ?? 'workspace',
-    defaultEnabled: rawManifest.defaultEnabled === true,
-    provides: normalizeStringArray(rawManifest.provides, 'plugin provides'),
-    requires: normalizeRequires(rawManifest.requires),
-    contributes: normalizeContributes(rawManifest.contributes),
-    lifecycle: normalizeLifecycle(rawManifest.lifecycle),
+    ...appMetadata,
+    id: id ?? packageName,
+    name: name ?? id ?? packageName,
+    version,
+    enabled: enabled !== false,
+    provides: normalizeStringArray(provides, 'plugin provides'),
+    requires: normalizeRequires(requires),
+    lifecycle: normalizeLifecycle(lifecycle),
   };
 
   if (typeof manifest.id !== 'string' || !ID_PATTERN.test(manifest.id)) {
@@ -75,13 +77,6 @@ function validateManifest(rawManifest, { packageName } = {}) {
   if (typeof manifest.version !== 'string' || manifest.version === '') {
     throw new Error(`plugin ${manifest.id} version must be a non-empty string`);
   }
-  if (!KINDS.has(manifest.kind)) {
-    throw new Error(`plugin ${manifest.id} kind must be core or feature`);
-  }
-  if (!SCOPES.has(manifest.scope)) {
-    throw new Error(`plugin ${manifest.id} scope must be global or workspace`);
-  }
-
   return manifest;
 }
 

package/server/session/index.js

@@ -4,29 +4,71 @@ import { SESSION_COOKIE_MAX_AGE_SKEW } from '../constants.js';
 import { toErrorMessage } from '../helpers.js';
 import { normalizeDurationSeconds } from '../config/duration.js';
 const MIN_PASSWORD_LENGTH = 32;
-function resolveSessionConfig(config, mode) {
+
+function assertPasswordLength(password, label) {
+  if (typeof password !== 'string') return;
+  if (password.length < MIN_PASSWORD_LENGTH) {
+    throw new Error(
+      `${label} must be at least ${MIN_PASSWORD_LENGTH} characters (got ${password.length}). Short passwords produce weak encryption.`,
+    );
+  }
+}
+
+function normalizePasswordConfig(config) {
+  if (Array.isArray(config.keyring) && config.keyring.length > 0) {
+    const password = {};
+    for (const entry of config.keyring) {
+      const id = String(entry.id ?? '');
+      if (!id) throw new Error('Session keyring entries require stable ids');
+      if (!/^\d+$/.test(id)) throw new Error(`Session keyring id=${id} must be numeric`);
+      assertPasswordLength(entry.password, `Session password id=${id}`);
+      password[id] = entry.password;
+    }
+
+    const active = config.keyring.at(-1);
+    const activeId = String(active.id);
+    return {
+      password,
+      sealPassword: { [activeId]: active.password },
+      activePasswordId: activeId,
+    };
+  }
+
   if (!config.password) {
     throw new Error(
-      `Session "password" is required but was not provided (got ${config.password === void 0 ? 'undefined' : String(config.password)}). Set a password of at least 32 characters, e.g. via SESSION_SECRET env variable.`,
+      `Session "password" is required but was not provided (got ${config.password === void 0 ? 'undefined' : String(config.password)}). Set vault.masterSecret to provide a session key.`,
     );
   }
+
   if (typeof config.password === 'string') {
-    if (config.password.length < MIN_PASSWORD_LENGTH) {
-      throw new Error(
-        `Session password must be at least ${MIN_PASSWORD_LENGTH} characters (got ${config.password.length}). Short passwords produce weak encryption.`,
-      );
-    }
-  } else if (typeof config.password === 'object') {
+    assertPasswordLength(config.password, 'Session password');
+    return {
+      password: config.password,
+      sealPassword: config.password,
+      activePasswordId: null,
+    };
+  }
+
+  if (typeof config.password === 'object') {
     for (const [id, pw] of Object.entries(config.password)) {
-      if (typeof pw === 'string' && pw.length < MIN_PASSWORD_LENGTH) {
-        throw new Error(
-          `Session password id=${id} must be at least ${MIN_PASSWORD_LENGTH} characters (got ${pw.length}). Short passwords produce weak encryption.`,
-        );
-      }
+      assertPasswordLength(pw, `Session password id=${id}`);
     }
+    return {
+      password: config.password,
+      sealPassword: config.password,
+      activePasswordId: String(Math.max(...Object.keys(config.password).map(Number))),
+    };
   }
+
+  throw new Error('Session password must be a string or password map');
+}
+
+function resolveSessionConfig(config, mode) {
+  const { password, sealPassword, activePasswordId } = normalizePasswordConfig(config);
   return {
-    password: config.password,
+    password,
+    sealPassword,
+    activePasswordId,
     cookieName: config.cookieName ?? 'arcway.session',
     ttl:
       config.ttl === undefined
@@ -60,7 +102,7 @@ async function unsealSession(cookieValue, config) {
 }
 async function sealSession(data, config) {
   return sealData(data, {
-    password: config.password,
+    password: config.sealPassword ?? config.password,
     ttl: config.ttl,
   });
 }

package/server/testing/index.js

@@ -188,6 +188,7 @@ async function testBoot(options) {
     },
     mail: { send: async () => ({ accepted: [], rejected: [] }), queue: async () => {} },
     log: { debug() {}, info() {}, warn() {}, error() {} },
+    vault: app.config?.vault,
   };
   async function request(method, urlPath, opts) {
     const url = new URL(urlPath, baseUrl);

package/server/config/modules/secrets.js

@@ -1,145 +0,0 @@
-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;