arcway 0.2.1 → 0.3.0

package/package.json

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

package/server/boot/index.js

@@ -19,6 +19,9 @@ 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 { CallbackDispatcher, CallbackRegistry } from '../callbacks/index.js';
+import { CallbackStore } from '../callbacks/store.js';
+import { discoverRootCallbacks } from '../callbacks/discovery.js';
 import path from 'node:path';
 
 async function boot(options) {
@@ -35,6 +38,12 @@ async function boot(options) {
 
   const infrastructure = await createInfrastructure(config, { runMigrations: true });
   const { db, redis, queue, cache, files, mail, events, log } = infrastructure;
+  const callbackStore = new CallbackStore(db);
+  await callbackStore.init();
+  const callbacks = new CallbackRegistry({
+    store: callbackStore,
+    secret: config.vault?.values?.callback,
+  });
   const meta = await collectRuntimeMeta(rootDir);
 
   if (envFiles.length > 0) log.info('Env files loaded', { envFiles });
@@ -58,6 +67,7 @@ async function boot(options) {
     fileWatcher,
     meta,
     vault: config.vault,
+    callbacks,
   };
 
   plugins.log = log;
@@ -98,6 +108,7 @@ async function boot(options) {
     log,
     meta,
     vault: config.vault,
+    callbacks,
     workerPool,
     plugins,
   });
@@ -113,7 +124,7 @@ async function boot(options) {
     sessionConfig: config.session,
   });
   await apiRouter.init();
-  if (fileWatcher) plugins.watch(fileWatcher, { apiRouter, jobRunner });
+  if (fileWatcher) plugins.watch(fileWatcher, { jobRunner });
 
   const pagesRouter = new PagesRouter(config, { rootDir, log, mode, fileWatcher, appContext });
   await pagesRouter.init();
@@ -128,7 +139,17 @@ async function boot(options) {
     db,
     redisClients: [{ name: 'redis', client: redis?.client }],
   };
-  const systemRouter = new SystemRouter({ healthDeps });
+  const callbackHandlers = await discoverRootCallbacks(rootDir);
+  const pluginCallbacks = (await plugins.discoverCallbacks?.()) ?? new Map();
+  for (const [name, callback] of pluginCallbacks) callbackHandlers.set(name, callback);
+  const callbackDispatcher = new CallbackDispatcher({
+    appContext,
+    callbacks: callbackHandlers,
+    registry: callbacks,
+    sessionConfig: config.session,
+    log,
+  });
+  const systemRouter = new SystemRouter({ healthDeps, callbackDispatcher });
 
   const staticRouter = new StaticRouter({
     outDir: pagesOutDir,

package/server/build.js

@@ -28,7 +28,6 @@ async function validateServerModules(config) {
   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) {

package/server/callbacks/cleanup-job.js

@@ -0,0 +1,12 @@
+import { CallbackStore } from './store.js';
+
+const cleanupCallbacksJob = {
+  name: 'cleanup-callbacks',
+  schedule: '*/15 * * * *',
+  handler: async (ctx) => {
+    const store = new CallbackStore(ctx.db);
+    await store.cleanup();
+  },
+};
+
+export { cleanupCallbacksJob };

package/server/callbacks/discovery.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { discoverModules } from '../discovery.js';
+
+function callbackName(relativePath) {
+  return relativePath.replace(/\\/g, '/').replace(/\.js$/, '');
+}
+
+function buildCallbacksFromModules(entries, { prefix = '' } = {}) {
+  const callbacks = new Map();
+  for (const entry of entries) {
+    const handler = entry.module.default ?? entry.module.handler;
+    if (typeof handler !== 'function') {
+      throw new Error(`Callback at ${entry.filePath} must export a handler function`);
+    }
+    const name = `${prefix}${callbackName(entry.relativePath)}`;
+    callbacks.set(name, { name, filePath: entry.filePath, handler });
+  }
+  return callbacks;
+}
+
+async function discoverCallbacks(callbacksDir) {
+  const entries = await discoverModules(callbacksDir, {
+    recursive: true,
+    label: 'callback file',
+  });
+  return buildCallbacksFromModules(entries);
+}
+
+async function discoverRootCallbacks(rootDir) {
+  return discoverCallbacks(path.join(rootDir, 'callbacks'));
+}
+
+export { buildCallbacksFromModules, discoverCallbacks, discoverRootCallbacks };

package/server/callbacks/index.js

@@ -0,0 +1,173 @@
+import { serializeResponse, sendJson } from '../router/http-helpers.js';
+import { buildSessionClearCookie, buildSessionSetCookie, sealSession } from '../session/index.js';
+import { buildContext } from '../context.js';
+import { CallbackRateLimiter } from './rate-limit.js';
+import { sealCallbackToken, unsealCallbackToken } from './tokens.js';
+
+function getCallbackToken(req, params) {
+  const state = req.query?.state ?? params.query?.get?.('state');
+  if (state) return state;
+  const pathToken = params.path && params.path !== '/' ? params.path.replace(/^\/+/, '') : '';
+  return pathToken ? decodeURIComponent(pathToken) : null;
+}
+
+function buildReqInfo(req) {
+  return {
+    id: req.id,
+    ip: req.ip,
+    method: req.method ?? 'GET',
+    path: (req.url ?? '/').split('?')[0],
+    query: req.query ?? {},
+    body: req.body,
+    rawBody: req.rawBody,
+    headers: req.flatHeaders ?? {},
+    cookies: req.cookies ?? {},
+    session: req.session,
+  };
+}
+
+class CallbackRegistry {
+  constructor({ store, secret }) {
+    this.store = store;
+    this.secret = secret;
+  }
+
+  bind(ctx) {
+    return {
+      register: async ({ handler, payload, oneTime = true, ttl } = {}) => {
+        if (!this.secret) throw new Error('Callback key is required');
+        const boundToSession =
+          oneTime !== false ? (ctx.req?.session?.id ?? ctx.req?.session?.userId ?? null) : null;
+        const row = await this.store.register({
+          handler,
+          payload,
+          oneTime,
+          ttl,
+          boundToSession,
+        });
+        return sealCallbackToken({ id: row.id, expiresAt: row.expiresAt }, this.secret);
+      },
+    };
+  }
+}
+
+class CallbackDispatcher {
+  constructor({ appContext, callbacks, registry, sessionConfig, log, rateLimiter } = {}) {
+    this.appContext = appContext;
+    this.callbacks = callbacks ?? new Map();
+    this.registry = registry;
+    this.sessionConfig = sessionConfig ?? null;
+    this.log = log;
+    this.rateLimiter = rateLimiter ?? new CallbackRateLimiter();
+  }
+
+  async handle(req, res, params) {
+    const rate = this.rateLimiter.check(req.ip);
+    if (!rate.allowed) {
+      sendJson(
+        res,
+        429,
+        { error: { code: 'RATE_LIMITED', message: 'Callback rate limit exceeded' } },
+        {
+          'X-RateLimit-Remaining': '0',
+          'X-RateLimit-Reset': String(rate.resetAt),
+          'Retry-After': String(Math.max(1, rate.resetAt - Math.ceil(Date.now() / 1000))),
+        },
+      );
+      return;
+    }
+
+    const token = getCallbackToken(req, params);
+    if (!token) {
+      sendJson(res, 400, {
+        error: { code: 'CALLBACK_TOKEN_REQUIRED', message: 'Callback token is required' },
+      });
+      return;
+    }
+
+    let sealed;
+    try {
+      sealed = await unsealCallbackToken(token, this.registry.secret);
+    } catch {
+      sendJson(res, 400, {
+        error: { code: 'INVALID_CALLBACK_TOKEN', message: 'Invalid callback token' },
+      });
+      return;
+    }
+
+    const row = await this.registry.store.consume(sealed.id);
+    if (!row) {
+      sendJson(res, 410, {
+        error: { code: 'CALLBACK_EXPIRED_OR_USED', message: 'Callback expired or already used' },
+      });
+      return;
+    }
+
+    if (row.boundToSession) {
+      const sessionId = req.session?.id ?? req.session?.userId ?? null;
+      if (sessionId !== row.boundToSession) {
+        sendJson(res, 403, {
+          error: { code: 'CALLBACK_SESSION_MISMATCH', message: 'Callback session mismatch' },
+        });
+        return;
+      }
+    }
+
+    const target = this.callbacks.get(row.target);
+    if (!target) {
+      sendJson(res, 404, {
+        error: { code: 'CALLBACK_HANDLER_NOT_FOUND', message: 'Callback handler not found' },
+      });
+      return;
+    }
+
+    const ctx = buildContext(
+      {
+        ...this.appContext,
+        log: this.log?.extend ? this.log.extend({ requestId: req.id }) : this.appContext.log,
+      },
+      {
+        req: buildReqInfo(req),
+        callback: { payload: row.payload, target: row.target, id: row.id },
+      },
+    );
+
+    let response;
+    try {
+      response = await target.handler(ctx);
+    } catch (err) {
+      this.log?.error?.('Callback handler error', { target: row.target, error: String(err) });
+      sendJson(res, 500, {
+        error: { code: 'CALLBACK_HANDLER_ERROR', message: 'Callback handler error' },
+      });
+      return;
+    }
+
+    const responseHeaders = { ...(response?.headers ?? {}) };
+    if (response?.redirect) {
+      res.writeHead(response.status ?? 302, { ...responseHeaders, Location: response.redirect });
+      res.end();
+      return;
+    }
+    if (response?.session !== void 0) {
+      if (!this.sessionConfig) {
+        throw new Error('Callback handler returned session but no session is configured');
+      }
+      responseHeaders['Set-Cookie'] =
+        response.session === null
+          ? buildSessionClearCookie(this.sessionConfig)
+          : buildSessionSetCookie(
+              await sealSession(response.session, this.sessionConfig),
+              this.sessionConfig,
+            );
+    }
+    await serializeResponse(
+      res,
+      response ?? { data: null },
+      responseHeaders,
+      response?.status ?? 200,
+    );
+  }
+}
+
+export { CallbackDispatcher, CallbackRegistry };

package/server/callbacks/rate-limit.js

@@ -0,0 +1,32 @@
+const DEFAULT_CALLBACK_RATE_LIMIT = Object.freeze({
+  max: 30,
+  windowMs: 60_000,
+});
+
+class CallbackRateLimiter {
+  constructor({
+    max = DEFAULT_CALLBACK_RATE_LIMIT.max,
+    windowMs = DEFAULT_CALLBACK_RATE_LIMIT.windowMs,
+  } = {}) {
+    this.max = max;
+    this.windowMs = windowMs;
+    this.buckets = new Map();
+  }
+
+  check(ip = 'unknown', now = Date.now()) {
+    const key = String(ip || 'unknown');
+    let bucket = this.buckets.get(key);
+    if (!bucket || bucket.resetAt <= now) {
+      bucket = { count: 0, resetAt: now + this.windowMs };
+      this.buckets.set(key, bucket);
+    }
+    bucket.count += 1;
+    return {
+      allowed: bucket.count <= this.max,
+      remaining: Math.max(0, this.max - bucket.count),
+      resetAt: Math.ceil(bucket.resetAt / 1000),
+    };
+  }
+}
+
+export { CallbackRateLimiter, DEFAULT_CALLBACK_RATE_LIMIT };

package/server/callbacks/store.js

@@ -0,0 +1,121 @@
+import { randomUUID } from 'node:crypto';
+
+const CALLBACK_TABLE = 'arcway_callbacks';
+const DEFAULT_CALLBACK_TTL_SECONDS = 600;
+const DEFAULT_CLEANUP_GRACE_SECONDS = 3600;
+
+function toIso(value) {
+  return new Date(value).toISOString();
+}
+
+function serializePayload(payload) {
+  return JSON.stringify(payload ?? null);
+}
+
+function parseRow(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    target: row.target,
+    payload: JSON.parse(row.payload),
+    oneTime: Boolean(row.one_time),
+    used: Boolean(row.used),
+    boundToSession: row.bound_to_session ?? null,
+    expiresAt: row.expires_at,
+  };
+}
+
+class CallbackStore {
+  constructor(db, { tableName = CALLBACK_TABLE } = {}) {
+    this.db = db;
+    this.tableName = tableName;
+  }
+
+  async init() {
+    if (!this.db) return;
+    const exists = await this.db.schema.hasTable(this.tableName);
+    if (exists) return;
+    await this.db.schema.createTable(this.tableName, (table) => {
+      table.string('id').primary();
+      table.string('target').notNullable().index();
+      table.text('payload').notNullable();
+      table.boolean('one_time').notNullable().defaultTo(true);
+      table.boolean('used').notNullable().defaultTo(false).index();
+      table.string('bound_to_session').nullable().index();
+      table.timestamp('expires_at').notNullable().index();
+      table.timestamp('created_at').defaultTo(this.db.fn.now());
+      table.timestamp('updated_at').defaultTo(this.db.fn.now());
+    });
+  }
+
+  async register({ handler, payload, oneTime = true, ttl, boundToSession }) {
+    if (!this.db) throw new Error('Callback registration requires a database');
+    if (!handler || typeof handler !== 'string') {
+      throw new Error('Callback handler must be a non-empty string');
+    }
+    const ttlSeconds = ttl ?? DEFAULT_CALLBACK_TTL_SECONDS;
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+      throw new Error('Callback ttl must be a positive number of seconds');
+    }
+
+    const now = Date.now();
+    const row = {
+      id: randomUUID(),
+      target: handler,
+      payload: serializePayload(payload),
+      one_time: oneTime !== false,
+      used: false,
+      bound_to_session: boundToSession ?? null,
+      expires_at: toIso(now + ttlSeconds * 1000),
+      created_at: toIso(now),
+      updated_at: toIso(now),
+    };
+    await this.db(this.tableName).insert(row);
+    return parseRow(row);
+  }
+
+  async claim(id, now = new Date()) {
+    const nowIso = toIso(now);
+    return this.db.transaction(async (trx) => {
+      const updated = await trx(this.tableName)
+        .where('id', id)
+        .andWhere('one_time', true)
+        .andWhere('used', false)
+        .andWhere('expires_at', '>', nowIso)
+        .update({ used: true, updated_at: nowIso });
+      if (updated === 0) return null;
+      const row = await trx(this.tableName).where('id', id).first();
+      return parseRow(row);
+    });
+  }
+
+  async getActive(id, now = new Date()) {
+    const row = await this.db(this.tableName)
+      .where('id', id)
+      .andWhere('one_time', false)
+      .andWhere('expires_at', '>', toIso(now))
+      .first();
+    if (!row || row.used) return null;
+    return parseRow(row);
+  }
+
+  async consume(id, now = new Date()) {
+    const claimed = await this.claim(id, now);
+    if (claimed) return claimed;
+    return this.getActive(id, now);
+  }
+
+  async cleanup({ graceSeconds = DEFAULT_CLEANUP_GRACE_SECONDS } = {}) {
+    const now = Date.now();
+    const expiredCutoff = toIso(now);
+    const usedCutoff = toIso(now - graceSeconds * 1000);
+    return this.db(this.tableName)
+      .where('expires_at', '<=', expiredCutoff)
+      .orWhere(function () {
+        this.where('used', true).andWhere('updated_at', '<=', usedCutoff);
+      })
+      .delete();
+  }
+}
+
+export { CALLBACK_TABLE, CallbackStore };

package/server/callbacks/tokens.js

@@ -0,0 +1,44 @@
+import { sealData, unsealData } from 'iron-session';
+
+function requireCallbackKey(secret) {
+  if (!secret) {
+    throw new Error('Callback key is required');
+  }
+  return secret;
+}
+
+async function sealCallbackToken({ id, expiresAt }, secret) {
+  const exp = new Date(expiresAt).getTime();
+  if (!id || !Number.isFinite(exp)) {
+    throw new Error('Callback token requires id and expiresAt');
+  }
+  return sealData(
+    { id, exp },
+    {
+      password: requireCallbackKey(secret),
+      ttl: 0,
+    },
+  );
+}
+
+async function unsealCallbackToken(token, secret, now = Date.now()) {
+  let data;
+  try {
+    data = await unsealData(token, {
+      password: requireCallbackKey(secret),
+      ttl: 0,
+    });
+  } catch {
+    throw new Error('Invalid callback token');
+  }
+
+  if (!data || typeof data !== 'object' || typeof data.id !== 'string') {
+    throw new Error('Invalid callback token');
+  }
+  if (!Number.isFinite(data.exp) || data.exp <= now) {
+    throw new Error('Callback token expired');
+  }
+  return { id: data.id, exp: data.exp };
+}
+
+export { sealCallbackToken, unsealCallbackToken };

package/server/context.js

@@ -154,6 +154,7 @@ function buildContext(appContext, extras) {
     _dbStats: tracked.stats,
     ...normalizedExtras,
   };
+  ctx.callbacks = appContext.callbacks?.bind?.(ctx);
   ctx.plugins = appContext.plugins?.buildContextProxy?.(ctx);
   return ctx;
 }

package/server/jobs/runner.js

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

package/server/jobs/worker-entry.js

@@ -4,6 +4,8 @@ import { serializeError } from './worker-pool.js';
 import { resolveWorkerConfig } from './worker-config.js';
 import { buildContext } from '../context.js';
 import { createInfrastructure, destroyInfrastructure } from '../boot/infrastructure.js';
+import { CallbackRegistry } from '../callbacks/index.js';
+import { CallbackStore } from '../callbacks/store.js';
 
 // Worker-side entry for the jobs WorkerPool. Each worker owns its own DB /
 // redis / queue / cache / files / mail / events / log — built lazily on the
@@ -70,8 +72,14 @@ 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 callbackStore = new CallbackStore(services.db);
+    await callbackStore.init();
+    const callbacks = new CallbackRegistry({
+      store: callbackStore,
+      secret: resolvedConfig?.vault?.values?.callback,
+    });
     const ctx = buildContext(
-      { ...services, meta: workerData?.meta, vault: resolvedConfig?.vault },
+      { ...services, meta: workerData?.meta, vault: resolvedConfig?.vault, callbacks },
       { payload },
     );
     return fn(ctx);

package/server/lib/vault/secrets.js

@@ -5,7 +5,7 @@ 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', 'jwt']);
+const SECRET_NAMES = Object.freeze(['session', 'plugin-vault', 'mcp-api', 'jwt', 'callback']);
 
 function base64Url(buffer) {
   return Buffer.from(buffer).toString('base64url');
@@ -103,6 +103,7 @@ function deriveInfraSecret(master, name) {
   if (name === 'plugin-vault') return formatVaultKey(deriveBytes(master, name, VAULT_KEY_BYTES));
   if (name === 'mcp-api') return base64Url(deriveBytes(master, name, 48));
   if (name === 'jwt') return base64Url(deriveBytes(master, name, 48));
+  if (name === 'callback') return base64Url(deriveBytes(master, name, 48));
   throw new Error(`Unknown Arcway infra secret namespace: ${name}`);
 }
 

package/server/plugins/bundle.js

@@ -32,15 +32,15 @@ async function loadPluginBundle(packageDir) {
 
   const pluginJs = path.join(packageDir, 'plugin.js');
   const exportsJs = path.join(packageDir, 'exports.js');
-  const routesDir = path.join(packageDir, 'routes');
   const jobsDir = path.join(packageDir, 'jobs');
+  const callbacksDir = path.join(packageDir, 'callbacks');
   const capabilitiesDir = path.join(packageDir, 'capabilities');
   const hooksDir = path.join(packageDir, 'hooks');
 
   const hasPluginJs = await exists(pluginJs);
   const hasExportsJs = await exists(exportsJs);
-  const routes = await discoverFiles(routesDir, { recursive: true });
   const jobs = await discoverFiles(jobsDir, { recursive: true });
+  const callbacks = await discoverFiles(callbacksDir, { recursive: true });
   const capabilities = await discoverFiles(capabilitiesDir);
   const hooks = await discoverFiles(hooksDir);
 
@@ -48,12 +48,12 @@ async function loadPluginBundle(packageDir) {
   if (hasPluginJs) lines.push(importLine('pluginModule', pluginJs));
   if (hasExportsJs) lines.push(importLine('pluginExports', exportsJs, false));
 
-  for (const [index, entry] of routes.entries()) {
-    lines.push(importLine(`route${index}`, entry.filePath));
-  }
   for (const [index, entry] of jobs.entries()) {
     lines.push(importLine(`job${index}`, entry.filePath));
   }
+  for (const [index, entry] of callbacks.entries()) {
+    lines.push(importLine(`callback${index}`, entry.filePath));
+  }
   for (const [index, entry] of capabilities.entries()) {
     lines.push(importLine(`capability${index}`, entry.filePath, false));
   }
@@ -66,10 +66,10 @@ async function loadPluginBundle(packageDir) {
     `export const exportsModule = ${hasExportsJs ? '{ default: pluginExports }' : 'null'};`,
   );
   lines.push(
-    `export const routes = [${routes.map((entry, index) => moduleEntry(`route${index}`, entry)).join(',')}];`,
+    `export const jobs = [${jobs.map((entry, index) => moduleEntry(`job${index}`, entry)).join(',')}];`,
   );
   lines.push(
-    `export const jobs = [${jobs.map((entry, index) => moduleEntry(`job${index}`, entry)).join(',')}];`,
+    `export const callbacks = [${callbacks.map((entry, index) => moduleEntry(`callback${index}`, entry)).join(',')}];`,
   );
   lines.push(
     `export const capabilities = {${capabilities
@@ -107,8 +107,8 @@ async function loadPluginBundle(packageDir) {
   return {
     module: bundled.module ?? {},
     exportsModule: bundled.exportsModule ?? null,
-    routes: bundled.routes ?? [],
     jobs: bundled.jobs ?? [],
+    callbacks: bundled.callbacks ?? [],
     capabilities: bundled.capabilities ?? {},
     hooks: bundled.hooks ?? {},
     artifact: outFile,

package/server/plugins/discovery.js

@@ -90,7 +90,7 @@ async function loadPluginPackage(packageDir, { bundle = false } = {}) {
     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/).
+    // and code is discovered by folder convention (jobs/, callbacks/, capabilities/, hooks/).
     manifestPath = packageJsonPath;
     rawManifest = {};
   } else {
@@ -111,8 +111,8 @@ async function loadPluginPackage(packageDir, { bundle = false } = {}) {
     { packageName: packageJson.name },
   );
 
-  const routesDir = path.join(packageDir, 'routes');
   const jobsDir = path.join(packageDir, 'jobs');
+  const callbacksDir = path.join(packageDir, 'callbacks');
   if (bundle && !bundled) bundled = await loadPluginBundle(packageDir);
   const exportsModule = bundled
     ? bundled.exportsModule
@@ -129,10 +129,10 @@ async function loadPluginPackage(packageDir, { bundle = false } = {}) {
     bundle: bundled ? { artifact: bundled.artifact } : null,
     manifestPath,
     exports: exportsModule ? getExports(exportsModule, exportsJs) : {},
-    routesDir: (await exists(routesDir)) ? routesDir : null,
     jobsDir: (await exists(jobsDir)) ? jobsDir : null,
-    bundledRoutes: bundled?.routes ?? null,
+    callbacksDir: (await exists(callbacksDir)) ? callbacksDir : null,
     bundledJobs: bundled?.jobs ?? null,
+    bundledCallbacks: bundled?.callbacks ?? null,
     capabilities:
       bundled?.capabilities ??
       (await loadConventionModules(path.join(packageDir, 'capabilities'), 'capability')),

package/server/plugins/manager.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
-import { buildRoutesFromModules, discoverRoutes } from '../router/routes.js';
 import { buildJobsFromModules, discoverJobs } from '../jobs/runner.js';
+import { buildCallbacksFromModules, discoverCallbacks } from '../callbacks/discovery.js';
 import { CapabilityRegistry } from './capabilities.js';
 import { discoverPlugins } from './discovery.js';
 import { buildProviderMap, cascadeDisabled, resolvePluginGraph } from './graph.js';
@@ -166,26 +166,6 @@ class PluginManager {
     };
   }
 
-  async discoverRoutes() {
-    const routes = [];
-    for (const plugin of this.enabledPlugins) {
-      const routeOptions = {
-        prefix: `/_plugins/${plugin.id}`,
-        plugin: {
-          id: plugin.id,
-          requires: plugin.manifest.requires,
-        },
-      };
-      const discovered = plugin.bundledRoutes
-        ? buildRoutesFromModules(plugin.bundledRoutes, routeOptions)
-        : plugin.routesDir
-          ? await discoverRoutes(plugin.routesDir, routeOptions)
-          : [];
-      routes.push(...discovered);
-    }
-    return routes;
-  }
-
   async discoverJobs() {
     const jobs = [];
     for (const plugin of this.enabledPlugins) {
@@ -209,6 +189,22 @@ class PluginManager {
     return jobs;
   }
 
+  async discoverCallbacks() {
+    const callbacks = new Map();
+    for (const plugin of this.enabledPlugins) {
+      const discovered = plugin.bundledCallbacks
+        ? buildCallbacksFromModules(plugin.bundledCallbacks)
+        : plugin.callbacksDir
+          ? await discoverCallbacks(plugin.callbacksDir)
+          : new Map();
+      for (const [name, callback] of discovered) {
+        const target = `plugins/${plugin.id}/${name}`;
+        callbacks.set(target, { ...callback, name: target, plugin });
+      }
+    }
+    return callbacks;
+  }
+
   async reload(ids) {
     if (this.config.enabled !== true) return { reloaded: [] };
 
@@ -298,7 +294,7 @@ class PluginManager {
     return ids;
   }
 
-  watch(fileWatcher, { apiRouter, jobRunner } = {}) {
+  watch(fileWatcher, { jobRunner } = {}) {
     if (this.config.enabled !== true || !fileWatcher) return;
     fileWatcher.subscribe('plugins', {
       dirs: this.config.dirs,
@@ -307,7 +303,6 @@ class PluginManager {
       onChange: async (events) => {
         const changedIds = this.pluginIdsForChangedFiles(events);
         await this.reload(changedIds);
-        await apiRouter?.reload?.();
         await jobRunner?.reload?.();
       },
     });

package/server/router/api-router.js

@@ -39,7 +39,6 @@ class ApiRouter {
   _appContext;
   _sessionConfig;
   _redis;
-  _pluginManager;
   _routes = [];
   _middleware = [];
   _prefix = '';
@@ -54,7 +53,6 @@ class ApiRouter {
     this._appContext = appContext ?? null;
     this._sessionConfig = sessionConfig ?? null;
     this._redis = appContext?.redis ?? null;
-    this._pluginManager = appContext?.plugins ?? null;
   }
 
   get routes() {
@@ -103,7 +101,6 @@ class ApiRouter {
     const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
     const ctx = this._buildCtx(reqInfo);
     try {
-      if (route.plugin) this._pluginManager?.injectCapabilities(ctx, route.plugin.requires);
       return await chainedHandler(ctx);
     } catch (err) {
       this._log.error(`Handler error in ${route.method} ${route.pattern}`, {
@@ -265,7 +262,6 @@ class ApiRouter {
 
     let response;
     try {
-      if (route.plugin) this._pluginManager?.injectCapabilities(ctx, route.plugin.requires);
       response = await chainedHandler(ctx);
     } catch (err) {
       const errorMsg = toErrorMessage(err);
@@ -358,12 +354,10 @@ class ApiRouter {
   }
 
   async _discover() {
-    const [routes, middleware, pluginRoutes] = await Promise.all([
+    const [routes, middleware] = await Promise.all([
       discoverRoutes(this._config.dir),
       discoverMiddleware(this._config.dir),
-      this._pluginManager?.discoverRoutes?.() ?? [],
     ]);
-    routes.push(...pluginRoutes);
     sortBySpecificity(routes);
 
     applyPrefix(routes, middleware, this._prefix);

package/server/system-jobs/index.js

@@ -1,5 +1,12 @@
+import { cleanupCallbacksJob } from '../callbacks/cleanup-job.js';
+
 const SYSTEM_JOB_DOMAIN = '__system';
 const systemJobRegistry = [
+  {
+    definition: cleanupCallbacksJob,
+    shouldRegister: (config) => Boolean(config.vault?.values?.callback && config.database),
+    description: 'Delete expired callback registrations',
+  },
   // Future system jobs are added here. Examples:
   //
   // {

package/server/system-routes/index.js

@@ -5,9 +5,11 @@ const SYSTEM_PREFIX = '/_system/api';
 class SystemRouter {
   routes = [];
   _healthDeps = null;
+  _callbackDispatcher = null;
 
-  constructor({ healthDeps } = {}) {
+  constructor({ healthDeps, callbackDispatcher } = {}) {
     this._healthDeps = healthDeps ?? null;
+    this._callbackDispatcher = callbackDispatcher ?? null;
   }
 
   register(route) {
@@ -23,6 +25,18 @@ class SystemRouter {
       return this._handleHealth(res);
     }
 
+    const pathname = url.split('?')[0];
+    if (
+      this._callbackDispatcher &&
+      (pathname === '/_system/callback' || pathname.startsWith('/_system/callback/'))
+    ) {
+      const fullPath = pathname;
+      const path = fullPath.slice('/_system/callback'.length) || '/';
+      const query = new URL(url, 'http://localhost').searchParams;
+      await this._callbackDispatcher.handle(req, res, { path, query, method });
+      return true;
+    }
+
     if (!url.startsWith(SYSTEM_PREFIX)) return false;
     const fullPath = url.split('?')[0];
     const routePath = fullPath.slice(SYSTEM_PREFIX.length) || '/';