arcway 0.1.30 → 0.2.1

package/package.json

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

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

@@ -28,7 +28,10 @@ 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 });
+  const plugins = await createPluginManager(config.plugins, {
+    runLifecycle: false,
+    bundle: mode === 'development',
+  });
 
   const infrastructure = await createInfrastructure(config, { runMigrations: true });
   const { db, redis, queue, cache, files, mail, events, log } = infrastructure;
@@ -43,7 +46,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;
@@ -82,6 +97,7 @@ async function boot(options) {
     events,
     log,
     meta,
+    vault: config.vault,
     workerPool,
     plugins,
   });
@@ -97,6 +113,7 @@ async function boot(options) {
     sessionConfig: config.session,
   });
   await apiRouter.init();
+  if (fileWatcher) plugins.watch(fileWatcher, { apiRouter, jobRunner });
 
   const pagesRouter = new PagesRouter(config, { rootDir, log, mode, fileWatcher, appContext });
   await pagesRouter.init();
@@ -153,6 +170,7 @@ async function boot(options) {
     if (workerPool) await workerPool.shutdown();
     await pagesRouter.close();
     await apiRouter.close();
+    if (fileWatcher) plugins.unwatch(fileWatcher);
     if (viteRouter) await viteRouter.close();
     await webServer.close();
     if (fileWatcher) await fileWatcher.close();

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

@@ -1,16 +1,28 @@
 import * as vault from './lib/vault/index.js';
+import { createJwtCodec } from './lib/vault/jwt.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 +113,18 @@ function normalizeMeta(meta) {
   };
 }
 
+function buildVaultToolkit(vaultConfig) {
+  if (!vaultConfig?.masterSecret) return vault;
+  const jwtCodec = createJwtCodec(vaultConfig.values?.jwt);
+
+  return {
+    ...vault,
+    ...jwtCodec,
+    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 +148,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/jobs/runner.js

@@ -5,8 +5,7 @@ import { toError, calculateBackoff } from './queue.js';
 import JobDispatcher from './drivers/memory-queue.js';
 import { SYSTEM_JOB_DOMAIN, registerSystemJobs } from '../system-jobs/index.js';
 
-async function discoverJobs(jobsDir) {
-  const entries = await discoverModules(jobsDir, { recursive: true, label: 'job file' });
+function buildJobsFromModules(entries) {
   const jobs = [];
   for (const { name, filePath, relativePath, module } of entries) {
     const job = module.default;
@@ -31,6 +30,11 @@ async function discoverJobs(jobsDir) {
   return jobs;
 }
 
+async function discoverJobs(jobsDir) {
+  const entries = await discoverModules(jobsDir, { recursive: true, label: 'job file' });
+  return buildJobsFromModules(entries);
+}
+
 class JobRunner {
   _dispatcher;
   _config;
@@ -42,11 +46,12 @@ class JobRunner {
   _timer = null;
   _started = false;
   _stopped = false;
+  _runGeneration = 0;
   _lastEnqueuedMinute = new Map();
 
   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 +60,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() {
@@ -135,10 +140,23 @@ class JobRunner {
     }
   }
 
+  async reload() {
+    const wasStarted = this._started;
+    this.stop();
+    this._jobs = [];
+    this._cronEntries = [];
+    this._continuousJobs = [];
+    this._lastEnqueuedMinute = new Map();
+    this._dispatcher.registered.clear();
+    await this.init();
+    if (wasStarted) this.start();
+  }
+
   start(intervalMs) {
     if (this._started) return;
     this._started = true;
     this._stopped = false;
+    const generation = ++this._runGeneration;
     const pollMs = intervalMs ?? this._config?.pollIntervalMs ?? 60000;
     this._timer = setInterval(() => {
       this.tick().catch((err) => {
@@ -146,7 +164,7 @@ class JobRunner {
       });
     }, pollMs);
     for (const entry of this._continuousJobs) {
-      this._runContinuousLoop(entry);
+      this._runContinuousLoop(entry, generation);
     }
 
     const parts = [];
@@ -158,6 +176,7 @@ class JobRunner {
   stop() {
     this._stopped = true;
     this._started = false;
+    this._runGeneration++;
     if (this._timer) {
       clearInterval(this._timer);
       this._timer = null;
@@ -188,12 +207,12 @@ class JobRunner {
     await this._dispatcher.process();
   }
 
-  async _runContinuousLoop(entry) {
+  async _runContinuousLoop(entry, generation) {
     const backoffMs = this._config?.backoffMs ?? 1000;
     const cooldownMs = entry.cooldownMs ?? this._config?.cooldownMs ?? 1000;
     let consecutiveErrors = 0;
     console.log(`[job-runner] continuous: ${entry.qualifiedName} started`);
-    while (!this._stopped) {
+    while (!this._stopped && generation === this._runGeneration) {
       try {
         const start = Date.now();
         const ctx = buildContext(entry.appContext, { payload: void 0 });
@@ -206,7 +225,7 @@ class JobRunner {
         if (cooldownMs > 0 && elapsed < cooldownMs) {
           const remaining = cooldownMs - elapsed;
           const deadline = Date.now() + remaining;
-          while (!this._stopped && Date.now() < deadline) {
+          while (!this._stopped && generation === this._runGeneration && Date.now() < deadline) {
             await new Promise((r) => setTimeout(r, Math.min(100, deadline - Date.now())));
           }
         }
@@ -219,7 +238,7 @@ class JobRunner {
           error.message,
         );
         const deadline = Date.now() + delay;
-        while (!this._stopped && Date.now() < deadline) {
+        while (!this._stopped && generation === this._runGeneration && Date.now() < deadline) {
           await new Promise((r) => setTimeout(r, Math.min(100, deadline - Date.now())));
         }
       }
@@ -228,4 +247,4 @@ class JobRunner {
   }
 }
 
-export { JobRunner, discoverJobs };
+export { JobRunner, buildJobsFromModules, discoverJobs };

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/jwt.js

@@ -1,19 +1,26 @@
-import { SignJWT, jwtVerify, errors } from 'jose';
+import { SignJWT, jwtVerify } from 'jose';
+
 function secretToKey(secret) {
   return new TextEncoder().encode(secret);
 }
+
 function parseExpiration(expiresIn) {
   if (typeof expiresIn === 'number') {
     return `${expiresIn}s`;
   }
   return expiresIn;
 }
-async function jwtEncode(payload, secret, options) {
+
+function requireJwtSecret(secret) {
   if (!secret) {
-    throw new Error('JWT secret is required');
+    throw new Error('JWT key is required');
   }
+  return secret;
+}
+
+async function encodeWithSecret(payload, secret, options) {
   const alg = options?.algorithm ?? 'HS256';
-  const key = secretToKey(secret);
+  const key = secretToKey(requireJwtSecret(secret));
   let builder = new SignJWT(payload).setProtectedHeader({ alg }).setIssuedAt();
   if (options?.expiresIn !== void 0) {
     builder = builder.setExpirationTime(parseExpiration(options.expiresIn));
@@ -26,11 +33,9 @@ async function jwtEncode(payload, secret, options) {
   }
   return builder.sign(key);
 }
-async function jwtDecode(token, secret, options) {
-  if (!secret) {
-    throw new Error('JWT secret is required');
-  }
-  const key = secretToKey(secret);
+
+async function decodeWithSecret(token, secret, options) {
+  const key = secretToKey(requireJwtSecret(secret));
   const algorithms = options?.algorithms ?? ['HS256'];
   try {
     const { payload } = await jwtVerify(token, key, {
@@ -39,17 +44,25 @@ async function jwtDecode(token, secret, options) {
       audience: options?.audience,
     });
     return payload;
-  } catch (err) {
-    if (err instanceof errors.JWTExpired) {
-      throw new Error('JWT token has expired');
-    }
-    if (err instanceof errors.JWSSignatureVerificationFailed) {
-      throw new Error('JWT signature verification failed');
-    }
-    if (err instanceof errors.JWTClaimValidationFailed) {
-      throw new Error(`JWT claim validation failed: ${err.message}`);
-    }
-    throw new Error(`JWT verification failed: ${err.message}`);
+  } catch {
+    throw new Error('JWT verification failed');
   }
 }
-export { jwtDecode, jwtEncode };
+
+function createJwtCodec(secret) {
+  const jwtSecret = requireJwtSecret(secret);
+  return {
+    jwtEncode: (payload, options) => encodeWithSecret(payload, jwtSecret, options),
+    jwtDecode: (token, options) => decodeWithSecret(token, jwtSecret, options),
+  };
+}
+
+async function jwtEncode(_payload, _options) {
+  throw new Error('JWT key is required; use ctx.vault.jwtEncode() with configured vault');
+}
+
+async function jwtDecode(_token, _options) {
+  throw new Error('JWT key is required; use ctx.vault.jwtDecode() with configured vault');
+}
+
+export { createJwtCodec, jwtDecode, jwtEncode };