arcway 0.1.0

package/server/lib/vault/password.js

@@ -0,0 +1,10 @@
+import bcrypt from 'bcryptjs';
+const DEFAULT_ROUNDS = 10;
+async function hashPassword(password, rounds = DEFAULT_ROUNDS) {
+  const salt = await bcrypt.genSalt(rounds);
+  return bcrypt.hash(password, salt);
+}
+async function verifyPassword(password, hash) {
+  return bcrypt.compare(password, hash);
+}
+export { hashPassword, verifyPassword };

package/server/lint/boundaries.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from '../glob.js';
+import { NODE_BUILTINS, SERVER_ONLY_PACKAGES } from '../constants.js';
+function extractImports(source) {
+  const imports = [];
+  const lines = source.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const lineText = lines[i];
+    const lineNum = i + 1;
+    const staticMatch = lineText.match(/(?:import|export)\s+.*?\s+from\s+['"]([^'"]+)['"]/);
+    if (staticMatch) {
+      imports.push({ path: staticMatch[1], line: lineNum });
+      continue;
+    }
+    const sideEffectMatch = lineText.match(/import\s+['"]([^'"]+)['"]/);
+    if (sideEffectMatch) {
+      imports.push({ path: sideEffectMatch[1], line: lineNum });
+      continue;
+    }
+    const dynamicMatch = lineText.match(/import\(\s*['"]([^'"]+)['"]\s*\)/);
+    if (dynamicMatch) {
+      imports.push({ path: dynamicMatch[1], line: lineNum });
+      continue;
+    }
+    const requireMatch = lineText.match(/require\(\s*['"]([^'"]+)['"]\s*\)/);
+    if (requireMatch) {
+      imports.push({ path: requireMatch[1], line: lineNum });
+    }
+  }
+  return imports;
+}
+function getPackageName(importPath) {
+  const parts = importPath.split('/');
+  return importPath.startsWith('@') && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+}
+async function checkServerClientBoundaries(rootDir) {
+  const violations = [];
+  let filesScanned = 0;
+  const clientPatterns = [
+    path.join(rootDir, 'client/**/*.{js,jsx}'),
+    path.join(rootDir, 'client/ui/**/*.{js,jsx}'),
+  ];
+  for (const pattern of clientPatterns) {
+    const files = await glob(pattern, { nodir: true });
+    for (const file of files) {
+      const source = await fs.readFile(file, 'utf-8');
+      const imports = extractImports(source);
+      filesScanned++;
+      for (const imp of imports) {
+        if (imp.path.startsWith('.')) continue;
+        if (NODE_BUILTINS.has(imp.path)) {
+          violations.push({
+            file: path.relative(rootDir, file),
+            line: imp.line,
+            kind: 'server-in-client',
+            importPath: imp.path,
+            message: `Client code cannot import Node.js built-in "${imp.path}". This module is not available in the browser.`,
+          });
+          continue;
+        }
+        const pkgName = getPackageName(imp.path);
+        if (SERVER_ONLY_PACKAGES.has(pkgName)) {
+          violations.push({
+            file: path.relative(rootDir, file),
+            line: imp.line,
+            kind: 'server-in-client',
+            importPath: imp.path,
+            message: `Client code cannot import server-only package "${pkgName}". This package requires Node.js and must not be in browser bundles.`,
+          });
+        }
+      }
+    }
+  }
+  return { violations, filesScanned };
+}
+export { checkServerClientBoundaries, extractImports };

package/server/logger/index.js

@@ -0,0 +1,130 @@
+import pino from 'pino';
+import RingBuffer from '../ring-buffer.js';
+
+function wrapPino(p) {
+  return {
+    debug(message, data) {
+      if (data) p.debug(data, message);
+      else p.debug(message);
+    },
+    info(message, data) {
+      if (data) p.info(data, message);
+      else p.info(message);
+    },
+    warn(message, data) {
+      if (data) p.warn(data, message);
+      else p.warn(message);
+    },
+    error(message, data) {
+      if (data) p.error(data, message);
+      else p.error(message);
+    },
+  };
+}
+
+class Logger {
+  _base;
+  _ring;
+  _fields;
+  _root;
+
+  constructor({ level, destination, buffer, pretty } = {}) {
+    const opts = {
+      level: level ?? 'info',
+      messageKey: 'message',
+      formatters: {
+        level(label) {
+          return { level: label };
+        },
+      },
+      timestamp: () => `,"time":"${new Date().toISOString()}"`,
+    };
+    if (!destination && pretty !== false) {
+      opts.transport = {
+        target: 'pino-pretty',
+        options: { colorize: true },
+      };
+    }
+    const p = destination ? pino(opts, destination) : pino(opts);
+    this._base = wrapPino(p);
+    this._ring = buffer ? new RingBuffer(buffer) : null;
+    this._fields = null;
+    this._root = null;
+  }
+
+  debug(message, data) {
+    this._log('debug', message, data);
+  }
+
+  info(message, data) {
+    this._log('info', message, data);
+  }
+
+  warn(message, data) {
+    this._log('warn', message, data);
+  }
+
+  error(message, data) {
+    this._log('error', message, data);
+  }
+
+  _log(level, message, data) {
+    const merged = this._fields ? (data ? { ...this._fields, ...data } : this._fields) : data;
+    if (this._root) {
+      this._root._log(level, message, merged);
+      return;
+    }
+    if (this._ring) {
+      this._ring.push({
+        level,
+        message,
+        ...(merged ? { data: merged } : {}),
+        timestamp: new Date().toISOString(),
+        ...(merged?.logger ? { logger: merged.logger } : {}),
+      });
+    }
+    this._base[level](message, merged);
+  }
+
+  query(filters) {
+    if (!this._ring) return [];
+    let entries = this._ring.toArray();
+    if (filters?.level) entries = entries.filter((e) => e.level === filters.level);
+    if (filters?.logger) entries = entries.filter((e) => e.logger === filters.logger);
+    if (filters?.requestId) entries = entries.filter((e) => e.data?.requestId === filters.requestId);
+    if (filters?.message) entries = entries.filter((e) => e.message === filters.message);
+    if (filters?.method) entries = entries.filter((e) => e.data?.method === filters.method.toUpperCase());
+    if (filters?.path) entries = entries.filter((e) => e.data?.path?.includes(filters.path));
+    if (filters?.status) entries = entries.filter((e) => e.data?.status === filters.status);
+    if (filters?.minDurationMs) entries = entries.filter((e) => e.data?.durationMs >= filters.minDurationMs);
+    if (filters?.eventName) {
+      entries = entries.filter((e) => e.data?.eventName === filters.eventName || e.data?.eventName?.includes(filters.eventName));
+    }
+    if (filters?.since) {
+      const sinceTs = new Date(filters.since).getTime();
+      entries = entries.filter((e) => new Date(e.timestamp).getTime() >= sinceTs);
+    }
+    if (filters?.limit && filters.limit > 0) entries = entries.slice(-filters.limit);
+    return entries;
+  }
+
+  errors(limit, since) {
+    return this.query({ level: 'error', limit, since });
+  }
+
+  extend(fields) {
+    const child = Object.create(Logger.prototype);
+    const hasFields = Object.keys(fields).length > 0;
+    child._fields = hasFields
+      ? this._fields
+        ? { ...this._fields, ...fields }
+        : fields
+      : this._fields;
+    child._root = this._root ?? this;
+    child._base = null;
+    child._ring = null;
+    return child;
+  }
+}
+
+export default Logger;

package/server/mail/drivers/console.js

@@ -0,0 +1,31 @@
+class ConsoleMailDriver {
+  /** Captured messages for test assertions. */
+  sent = [];
+  async send(message) {
+    this.sent.push(message);
+    const recipients = normalizeRecipients(message.to);
+    console.log(
+      '[mail] \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500',
+    );
+    console.log(`[mail] From:    ${message.from}`);
+    console.log(`[mail] To:      ${recipients.join(', ')}`);
+    if (message.cc) console.log(`[mail] CC:      ${normalizeRecipients(message.cc).join(', ')}`);
+    if (message.bcc) console.log(`[mail] BCC:     ${normalizeRecipients(message.bcc).join(', ')}`);
+    if (message.replyTo) console.log(`[mail] ReplyTo: ${message.replyTo}`);
+    console.log(`[mail] Subject: ${message.subject}`);
+    if (message.text) console.log(`[mail] Text:    ${message.text}`);
+    if (message.html) console.log(`[mail] HTML:    ${message.html}`);
+    console.log(
+      '[mail] \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500',
+    );
+    return {
+      accepted: recipients,
+      rejected: [],
+      messageId: `console-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@local`,
+    };
+  }
+}
+function normalizeRecipients(to) {
+  return Array.isArray(to) ? to : [to];
+}
+export default ConsoleMailDriver;

package/server/mail/drivers/smtp.js

@@ -0,0 +1,34 @@
+import { createTransport } from 'nodemailer';
+class SmtpMailDriver {
+  transporter;
+  constructor(smtpConfig) {
+    this.transporter = createTransport({
+      host: smtpConfig.host,
+      port: smtpConfig.port ?? 587,
+      secure: smtpConfig.secure ?? false,
+      auth: smtpConfig.auth ? { user: smtpConfig.auth.user, pass: smtpConfig.auth.pass } : void 0,
+    });
+  }
+  async send(message) {
+    const info = await this.transporter.sendMail({
+      from: message.from,
+      to: Array.isArray(message.to) ? message.to.join(', ') : message.to,
+      cc: message.cc ? (Array.isArray(message.cc) ? message.cc.join(', ') : message.cc) : void 0,
+      bcc: message.bcc
+        ? Array.isArray(message.bcc)
+          ? message.bcc.join(', ')
+          : message.bcc
+        : void 0,
+      replyTo: message.replyTo,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+    });
+    return {
+      accepted: Array.isArray(info.accepted) ? info.accepted.map(String) : [],
+      rejected: Array.isArray(info.rejected) ? info.rejected.map(String) : [],
+      messageId: info.messageId,
+    };
+  }
+}
+export default SmtpMailDriver;

package/server/mail/imap.js

@@ -0,0 +1,105 @@
+import { ImapFlow } from 'imapflow';
+import { simpleParser } from 'mailparser';
+import { toErrorMessage } from '../helpers.js';
+const DEFAULT_MAILBOX = 'INBOX';
+const DEFAULT_IMAP_PORT = 993;
+const SEEN_FLAG = '\\Seen';
+const LOG_PREFIX = '[mail/imap]';
+async function fetchUnseenMessages(config, log) {
+  const mailbox = config.mailbox ?? DEFAULT_MAILBOX;
+  const client = new ImapFlow({
+    host: config.host,
+    port: config.port ?? DEFAULT_IMAP_PORT,
+    secure: config.tls !== false,
+    auth: {
+      user: config.auth.user,
+      pass: config.auth.pass,
+    },
+    logger: false,
+    // Suppress imapflow's internal logging
+  });
+  const emails = [];
+  try {
+    await client.connect();
+  } catch (err) {
+    log.error(`${LOG_PREFIX} Failed to connect`, {
+      error: toErrorMessage(err),
+      host: config.host,
+    });
+    return emails;
+  }
+  try {
+    const lock = await client.getMailboxLock(mailbox);
+    try {
+      const messages = client.fetch(
+        { seen: false },
+        {
+          source: true,
+          uid: true,
+          flags: true,
+          envelope: true,
+        },
+      );
+      for await (const msg of messages) {
+        try {
+          const parsed = await simpleParser(msg.source);
+          const email = {
+            messageId: parsed.messageId || `unknown-${msg.uid}-${Date.now()}`,
+            from: extractAddress(parsed.from),
+            to: extractAddresses(parsed.to),
+            cc: parsed.cc ? extractAddresses(parsed.cc) : void 0,
+            subject: parsed.subject ?? '(no subject)',
+            text: parsed.text ?? void 0,
+            html: typeof parsed.html === 'string' ? parsed.html : void 0,
+            hasAttachments: (parsed.attachments?.length ?? 0) > 0,
+            date: parsed.date ?? new Date(),
+            headers: extractHeaders(parsed.headers),
+          };
+          emails.push(email);
+          await client.messageFlagsAdd({ uid: msg.uid }, [SEEN_FLAG], { uid: true });
+        } catch (parseErr) {
+          log.error(`${LOG_PREFIX} Failed to parse message`, {
+            uid: msg.uid,
+            error: parseErr instanceof Error ? parseErr.message : String(parseErr),
+          });
+        }
+      }
+    } finally {
+      lock.release();
+    }
+  } catch (err) {
+    log.error(`${LOG_PREFIX} Error fetching messages`, {
+      error: toErrorMessage(err),
+    });
+  } finally {
+    await client.logout().catch(() => {});
+  }
+  return emails;
+}
+function extractAddress(addr) {
+  if (!addr) return 'unknown@unknown';
+  if (addr.value && Array.isArray(addr.value) && addr.value.length > 0) {
+    return addr.value[0].address ?? 'unknown@unknown';
+  }
+  if (typeof addr === 'string') return addr;
+  return 'unknown@unknown';
+}
+function extractAddresses(addr) {
+  if (!addr) return [];
+  if (addr.value && Array.isArray(addr.value)) {
+    return addr.value.map((v) => v.address ?? 'unknown@unknown');
+  }
+  if (typeof addr === 'string') return [addr];
+  return [];
+}
+function extractHeaders(headers) {
+  const result = {};
+  if (!headers) return result;
+  if (typeof headers.forEach === 'function') {
+    headers.forEach((value, key) => {
+      result[key] = typeof value === 'string' ? value : String(value);
+    });
+  }
+  return result;
+}
+export { fetchUnseenMessages };

package/server/mail/inbound-store.js

@@ -0,0 +1,58 @@
+const INBOUND_MAIL_TABLE = '__inbound_mail';
+async function ensureInboundMailTable(db) {
+  const exists = await db.schema.hasTable(INBOUND_MAIL_TABLE);
+  if (exists) return;
+  await db.schema.createTable(INBOUND_MAIL_TABLE, (table) => {
+    table.increments('id').primary();
+    table.string('message_id').notNullable().unique();
+    table.string('from_addr').notNullable();
+    table.text('to_addrs').notNullable();
+    table.text('cc_addrs').nullable();
+    table.string('subject').nullable();
+    table.text('text_body').nullable();
+    table.text('html_body').nullable();
+    table.boolean('has_attachments').notNullable().defaultTo(false);
+    table.timestamp('received_at').notNullable();
+    table.timestamp('created_at').defaultTo(db.fn.now());
+  });
+}
+async function storeInboundEmail(db, email) {
+  try {
+    await db(INBOUND_MAIL_TABLE).insert({
+      message_id: email.messageId,
+      from_addr: email.from,
+      to_addrs: JSON.stringify(email.to),
+      cc_addrs: email.cc ? JSON.stringify(email.cc) : null,
+      subject: email.subject,
+      text_body: email.text ?? null,
+      html_body: email.html ?? null,
+      has_attachments: email.hasAttachments,
+      received_at: email.date.toISOString(),
+    });
+    return true;
+  } catch (err) {
+    if (
+      err.code === 'SQLITE_CONSTRAINT' ||
+      err.code === '23505' || // PostgreSQL unique violation
+      (err.message && err.message.includes('UNIQUE constraint failed'))
+    ) {
+      return false;
+    }
+    throw err;
+  }
+}
+async function pruneInboundEmails(db, retentionDays) {
+  const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1e3);
+  return db(INBOUND_MAIL_TABLE).where('received_at', '<', cutoff.toISOString()).delete();
+}
+async function hasMessage(db, messageId) {
+  const row = await db(INBOUND_MAIL_TABLE).where('message_id', messageId).first('id');
+  return !!row;
+}
+export {
+  INBOUND_MAIL_TABLE,
+  ensureInboundMailTable,
+  hasMessage,
+  pruneInboundEmails,
+  storeInboundEmail,
+};

package/server/mail/inbound.js

@@ -0,0 +1,79 @@
+import { addSystemJobEntry } from '../system-jobs/index.js';
+import { toErrorMessage } from '../helpers.js';
+import { fetchUnseenMessages } from './imap.js';
+import { ensureInboundMailTable, storeInboundEmail, pruneInboundEmails } from './inbound-store.js';
+const POLL_INBOUND_JOB_NAME = 'poll-inbound-mail';
+const PRUNE_INBOUND_JOB_NAME = 'prune-inbound-mail';
+const DEFAULT_RETENTION_DAYS = 30;
+const DEFAULT_POLL_INTERVAL_SECONDS = 30;
+function registerInboundMailJobs(db, inboundConfig, log, onEmail) {
+  if (inboundConfig.driver !== 'imap' || !inboundConfig.imap) {
+    throw new Error('mail.inbound.imap config is required when inbound driver is "imap"');
+  }
+  const imapConfig = inboundConfig.imap;
+  const pollSeconds = imapConfig.pollIntervalSeconds ?? DEFAULT_POLL_INTERVAL_SECONDS;
+  const cronMinutes = Math.max(1, Math.floor(pollSeconds / 60));
+  const cronExpr = cronMinutes === 1 ? '* * * * *' : `*/${cronMinutes} * * * *`;
+  addSystemJobEntry({
+    definition: {
+      name: POLL_INBOUND_JOB_NAME,
+      schedule: cronExpr,
+      handler: async () => {
+        log.info('[mail/inbound] Polling for new messages...');
+        const emails = await fetchUnseenMessages(imapConfig, log);
+        if (emails.length === 0) {
+          log.info('[mail/inbound] No new messages');
+          return;
+        }
+        log.info(`[mail/inbound] Fetched ${emails.length} new message(s)`);
+        let stored = 0;
+        for (const email of emails) {
+          const isNew = await storeInboundEmail(db, email);
+          if (isNew) {
+            stored++;
+            try {
+              await onEmail(email);
+            } catch (err) {
+              log.error('[mail/inbound] Error in email handler', {
+                messageId: email.messageId,
+                error: toErrorMessage(err),
+              });
+            }
+          } else {
+            log.info(`[mail/inbound] Duplicate skipped: ${email.messageId}`);
+          }
+        }
+        log.info(
+          `[mail/inbound] Stored ${stored} new message(s), ${emails.length - stored} duplicate(s)`,
+        );
+      },
+    },
+    shouldRegister: (config) => !!config.mail?.inbound,
+    description: 'Poll IMAP mailbox for inbound email',
+  });
+  const retentionDays = inboundConfig.retentionDays ?? DEFAULT_RETENTION_DAYS;
+  if (retentionDays && retentionDays > 0) {
+    addSystemJobEntry({
+      definition: {
+        name: PRUNE_INBOUND_JOB_NAME,
+        schedule: '0 3 * * *',
+        // Daily at 3 AM
+        handler: async () => {
+          log.info(`[mail/inbound] Pruning messages older than ${retentionDays} days...`);
+          const deleted = await pruneInboundEmails(db, retentionDays);
+          log.info(`[mail/inbound] Pruned ${deleted} message(s)`);
+        },
+      },
+      shouldRegister: (config) => {
+        const retention = config.mail?.inbound?.retentionDays;
+        return !!config.mail?.inbound && retention !== 0 && retention !== null;
+      },
+      description: 'Prune old inbound email messages',
+    });
+  }
+}
+async function initInboundMail(db, inboundConfig, log, onEmail) {
+  await ensureInboundMailTable(db);
+  registerInboundMailJobs(db, inboundConfig, log, onEmail);
+}
+export { POLL_INBOUND_JOB_NAME, PRUNE_INBOUND_JOB_NAME, initInboundMail, registerInboundMailJobs };

package/server/mail/index.js

@@ -0,0 +1,112 @@
+import { SYSTEM_JOB_DOMAIN } from '../system-jobs/index.js';
+import { addSystemJobEntry } from '../system-jobs/index.js';
+import ConsoleMailDriver from './drivers/console.js';
+import SmtpMailDriver from './drivers/smtp.js';
+import { initInboundMail } from './inbound.js';
+
+const MAIL_JOB_NAME = 'send-mail';
+const MAIL_JOB_QUALIFIED = `${SYSTEM_JOB_DOMAIN}/${MAIL_JOB_NAME}`;
+const MAIL_TOPIC = 'mail:outbound';
+
+class Mail {
+  _driver = null;
+  _config;
+  _db;
+  _log;
+  _queue = null;
+  _enabled = false;
+
+  constructor(config, { db, log, queue } = {}) {
+    this._config = config;
+    this._db = db;
+    this._log = log;
+    this._queue = queue;
+    this._enabled = !!(config && config.enabled !== false);
+
+    if (this._enabled) {
+      this._driver = createDriver(config);
+      registerSendJob(this._driver, queue, config.throughput);
+      log?.info(`Mail driver: ${config.driver}`);
+    } else if (config) {
+      log?.info('Mail: disabled');
+    }
+  }
+
+  get enabled() {
+    return this._enabled;
+  }
+
+  async send(message) {
+    if (!this._enabled || !this._driver) {
+      throw new Error(
+        'Mail is not configured. Add a "mail" section to your arcway.config.js to enable email.',
+      );
+    }
+    const from = message.from ?? this._config.from;
+    return this._driver.send({ ...message, from });
+  }
+
+  async queue(message) {
+    if (!this._enabled || !this._driver) {
+      throw new Error(
+        'Mail is not configured. Add a "mail" section to your arcway.config.js to enable email.',
+      );
+    }
+    if (!this._queue) {
+      throw new Error(
+        'Cannot queue mail: queue is not available. Use mail.send() for immediate delivery.',
+      );
+    }
+    const payload = {
+      ...message,
+      from: message.from ?? this._config.from,
+    };
+    await this._queue.push(MAIL_TOPIC, payload);
+  }
+
+  async initInbound(onEmail) {
+    if (!this._enabled || !this._config?.inbound) return;
+    await initInboundMail(this._db, this._config.inbound, this._log, onEmail);
+    this._log?.info(`Mail inbound: ${this._config.inbound.driver}`);
+  }
+}
+
+function createDriver(config) {
+  switch (config.driver) {
+    case 'smtp': {
+      if (!config.smtp) {
+        throw new Error('mail.smtp config is required when driver is "smtp"');
+      }
+      return new SmtpMailDriver(config.smtp);
+    }
+    case 'console':
+      return new ConsoleMailDriver();
+    default:
+      throw new Error(`Unknown mail driver: "${config.driver}"`);
+  }
+}
+
+function registerSendJob(driver, queue, throughput) {
+  addSystemJobEntry({
+    definition: {
+      name: MAIL_JOB_NAME,
+      handler: async () => {
+        if (!queue) return;
+        const items = await queue.pop(MAIL_TOPIC, 10);
+        const ids = [];
+        for (const item of items) {
+          await driver.send(item.data);
+          ids.push(item.id);
+        }
+        if (ids.length > 0) {
+          await queue.remove(ids);
+        }
+      },
+      throughput,
+    },
+    shouldRegister: (config) => !!config.mail,
+    description: 'Send queued outbound email',
+  });
+}
+
+export { MAIL_JOB_NAME, MAIL_JOB_QUALIFIED, MAIL_TOPIC, Mail };