Refactor server config: single --config flag replaces --secrets/--mail-perms

- New server/config.mjs loads config.json, resolves secrets path relative
  to config dir, returns users/smtp/mail_perms_path/bind/port
- server/secrets.mjs removed (logic absorbed into config.mjs)
- smtp moves from secrets.json to config.json
- secrets.json now contains only users (pure credentials)
- config.example.json added as reference template
- .gitignore/.npmignore updated to cover config.json and mail-perms.json
- README updated with new setup and flags

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -1,3 +1,5 @@
 node_modules/
 secrets.json
+config.json
+mail-perms.json
 package-lock.json

.npmignore

@@ -1,2 +1,4 @@
 secrets.json
 filtered-secrets.json
+config.json
+mail-perms.json

README.md

@@ -49,6 +49,28 @@ ccc-keygen --filter agent --output agent-secrets.json
 
 The full `secrets.json` stays on the host. `agent-secrets.json` goes into the container.
 
+### Create a config file
+
+Copy [`config.example.json`](config.example.json) to `config.json` and edit it:
+
+```json
+{
+    "secrets": "../secrets.json",
+    "mail_perms": "mail-perms.json",
+    "smtp": {
+        "host": "smtp.example.com",
+        "port": 587,
+        "secure": false,
+        "auth": { "user": "relay@example.com", "pass": "<password>" },
+        "from": "agent@example.com"
+    },
+    "bind": "127.0.0.1",
+    "port": 3015
+}
+```
+
+`secrets` and `mail_perms` paths are resolved relative to the config file. `smtp`, `mail_perms`, `bind`, and `port` are all optional.
+
 ---
 
 ## Running
@@ -56,24 +78,22 @@ The full `secrets.json` stays on the host. `agent-secrets.json` goes into the co
 ### Server (host)
 
 ```bash
-ccc-server --secrets secrets.json
-ccc-server --secrets secrets.json --mail-perms mail-perms.json
+ccc-server --config config.json
+ccc-server --config config.json --dry-run
 ```
 
 Server flags:
 | Flag | Env variable | Description |
 |------|-------------|-------------|
-| `--secrets <path>` | — | Path to secrets file (required) |
-| `--bind <addr>` | `CONDUIT_BIND` | Address to bind to (default `127.0.0.1`) |
-| `--mail-perms <path>` | `CONDUIT_MAIL_PERMS` | File to persist mail permissions (optional; in-memory only if omitted) |
+| `--config <path>` | `CONDUIT_CONFIG` | Path to config file (required) |
 | `--dry-run` | — | Log all action invocations but do not execute them |
 
-Server environment variables:
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CONDUIT_PORT` | `3015` | Port to listen on |
-| `CONDUIT_BIND` | `127.0.0.1` | Address to bind to |
-| `CONDUIT_ROOT` | `/workspace` | Label printed at startup (informational only — path resolution uses `VOLUME_MAPPING` in `server/helpers.mjs`) |
+Server environment variables (override config file values):
+| Variable | Description |
+|----------|-------------|
+| `CONDUIT_PORT` | Port to listen on |
+| `CONDUIT_BIND` | Address to bind to |
+| `CONDUIT_ROOT` | Label printed at startup (informational only — path resolution uses `VOLUME_MAPPING` in `server/helpers.mjs`) |
 
 ### Client (container / agent)
 
@@ -145,7 +165,7 @@ Built-in actions:
 | `open-browser` | queue | `url` (http/https only) |
 | `open-terminal` | queue | `path` (optional, defaults to workspace) |
 | `send-email` | auto-accept | `to`, `subject`, `body`, `topic` |
-| `set-mail-permission` | auto-accept | `target_user`, `to`, `topic`, `allow` (bool) |
+| `set-mail-permission` | auto-accept | `target_user`, `to`, `allow` (bool), `topic` (optional — omit to match any topic) |
 | `get-mail-permissions` | auto-accept | `target_user` (optional) |
 
 `send-email` checks that the caller has a mail permission entry matching `(caller, to, topic)` before sending. Permissions are managed via `set-mail-permission`, which requires the caller to have `canApprove` over the target user — so only humans can grant/revoke permissions for agents.

config.example.json

@@ -0,0 +1,13 @@
+{
+	"secrets": "../secrets.json",
+	"mail_perms": "mail-perms.json",
+	"smtp": {
+		"host": "smtp.example.com",
+		"port": 587,
+		"secure": false,
+		"auth": { "user": "relay@example.com", "pass": "<password>" },
+		"from": "agent@example.com"
+	},
+	"bind": "127.0.0.1",
+	"port": 3015
+}

secrets.example.json

@@ -1,11 +1,4 @@
 {
-	"smtp": {
-		"host": "smtp.example.com",
-		"port": 587,
-		"secure": false,
-		"auth": { "user": "relay@example.com", "pass": "<password>" },
-		"from": "agent@example.com"
-	},
 	"users": {
 		"<username>": { "secret": "<hex secret>", "canApprove": [] },
 		"<username>": { "secret": "<hex secret>", "canApprove": ["<username>"] }

server/actions.mjs

@@ -2,7 +2,7 @@
 // policy: "auto-accept" | "auto-deny" | "queue"
 
 
-import { resolve_path, exec } from './helpers.mjs';
+import { resolve_path } from './helpers.mjs';
 import { check_can_approve } from './auth.mjs';
 
 export const actions = {
@@ -24,7 +24,7 @@ export const actions = {
 		description: "Open a file in the editor",
 		params: [{ name: "filename", required: true, type: "path" }],
 		policy: "auto-accept",
-		handler: ({ filename }) => {
+		handler: ({ filename }, { exec }) => {
 			const resolved = resolve_path(filename);
 			exec('subl3', [resolved]);
 			return { opened: resolved };
@@ -48,7 +48,7 @@ export const actions = {
 		description: "Open a URL in the web browser",
 		params: [{ name: "url", required: true, type: "string" }],
 		policy: "queue",
-		handler: ({ url }) => {
+		handler: ({ url }, { exec }) => {
 			const parsed = new URL(url);
 			if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
 				throw new Error(`Disallowed protocol: ${parsed.protocol}`);
@@ -62,7 +62,7 @@ export const actions = {
 		description: "Open a terminal in a given directory",
 		params: [{ name: "path", required: false, type: "path" }],
 		policy: 'queue',
-		handler: ({ path }) => {
+		handler: ({ path }, { exec }) => {
 			const resolved = resolve_path(path ?? 'workspace');
 			exec('konsole', ['--workdir', resolved, '-e', 'bash']);
 			return { opened: resolved };
@@ -92,11 +92,11 @@ export const actions = {
 		params: [
 			{ name: 'target_user', required: true,  type: 'string' },
 			{ name: 'to',          required: true,  type: 'string' },
-			{ name: 'topic',       required: true,  type: 'string' },
+			{ name: 'topic',       required: false, type: 'string' },
 			{ name: 'allow',       required: true,  type: 'boolean' },
 		],
 		policy: 'auto-accept',
-		handler: ({ target_user, to, topic, allow }, { caller, users, mail_perm_store }) => {
+		handler: ({ target_user, to, topic = null, allow }, { caller, users, mail_perm_store }) => {
 			if (!check_can_approve(users, caller, target_user)) {
 				throw new Error(`Not authorized to set mail permissions for '${target_user}'`);
 			}

server/config.mjs

@@ -0,0 +1,56 @@
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+export function load_config(file_path) {
+	if (!file_path) {
+		throw new Error('--config <path> is required');
+	}
+	let raw;
+	try {
+		raw = readFileSync(file_path, 'utf8');
+	} catch (err) {
+		throw new Error(`Cannot read config file at ${file_path}: ${err.message}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Config file is not valid JSON: ${err.message}`);
+	}
+
+	if (!parsed.secrets) {
+		throw new Error("Config file must have a 'secrets' field pointing to the secrets file");
+	}
+
+	// Resolve secrets path relative to the config file's directory
+	const config_dir = resolve(file_path, '..');
+	const secrets_path = resolve(config_dir, parsed.secrets);
+
+	let secrets_raw;
+	try {
+		secrets_raw = readFileSync(secrets_path, 'utf8');
+	} catch (err) {
+		throw new Error(`Cannot read secrets file at ${secrets_path}: ${err.message}`);
+	}
+	let secrets;
+	try {
+		secrets = JSON.parse(secrets_raw);
+	} catch (err) {
+		throw new Error(`Secrets file is not valid JSON: ${err.message}`);
+	}
+	if (!secrets.users || typeof secrets.users !== 'object') {
+		throw new Error("Secrets file must have a top-level 'users' object");
+	}
+
+	const mail_perms_path = parsed.mail_perms
+		? resolve(config_dir, parsed.mail_perms)
+		: null;
+
+	return {
+		users:          secrets.users,
+		smtp:           parsed.smtp ?? null,
+		mail_perms_path,
+		bind:           parsed.bind ?? null,
+		port:           parsed.port ?? null,
+	};
+}

server/index.mjs

@@ -1,9 +1,10 @@
 import express from 'express';
 import { actions } from './actions.mjs';
 import { enqueue, get_entry, list_pending, resolve } from './queue.mjs';
-import { load_secrets } from './secrets.mjs';
+import { load_config } from './config.mjs';
 import { create_auth_middleware, check_can_approve } from './auth.mjs';
 import { create_mailer } from './mailer.mjs';
+import { exec as real_exec } from './helpers.mjs';
 import { load_mail_perms } from './mail_perms.mjs';
 
 function get_arg(argv, flag) {
@@ -15,22 +16,22 @@ function ts() {
 	return new Date().toLocaleTimeString();
 }
 
-const PORT     = process.env.CONDUIT_PORT || 3015;
-const BIND     = get_arg(process.argv, '--bind') || process.env.CONDUIT_BIND || '127.0.0.1';
 const VERBOSE  = process.argv.includes('--verbose');
 const DRY_RUN  = process.argv.includes('--dry-run');
 
-const secrets_path    = get_arg(process.argv, '--secrets');
-const mail_perms_path = get_arg(process.argv, '--mail-perms') || process.env.CONDUIT_MAIL_PERMS || null;
+const config_path = get_arg(process.argv, '--config') || process.env.CONDUIT_CONFIG;
 
-let secrets;
+let cfg;
 try {
-	secrets = load_secrets(secrets_path);
+	cfg = load_config(config_path);
 } catch (err) {
 	console.error(`Fatal: ${err.message}`);
 	process.exit(1);
 }
-const { users, smtp } = secrets;
+
+const { users, smtp, mail_perms_path } = cfg;
+const PORT  = process.env.CONDUIT_PORT || cfg.port  || 3015;
+const BIND  = process.env.CONDUIT_BIND || cfg.bind  || '127.0.0.1';
 
 let mail_perm_store;
 try {
@@ -41,10 +42,10 @@ try {
 }
 
 if (!mail_perms_path) {
-	console.warn('Warning: --mail-perms not set; mail permissions will not persist across restarts');
+	console.warn('Warning: mail_perms not set in config; mail permissions will not persist across restarts');
 }
 
-const mailer_send = create_mailer(smtp);
+const real_mailer_send = create_mailer(smtp);
 
 const app = express();
 app.use(express.json({
@@ -62,13 +63,17 @@ app.use((req, _res, next) => {
 	next();
 });
 
-async function run_action(def, action, params, ctx) {
-	if (DRY_RUN) {
-		console.log(`[${ts()}] [DRY-RUN] action: ${action}`);
-		console.log(`[${ts()}] [DRY-RUN] caller: ${ctx.caller}`);
-		console.log(`[${ts()}] [DRY-RUN] params: ${JSON.stringify(params, null, 2)}`);
-		return { dry_run: true, action, params };
+function make_ctx(caller) {
+	const exec = DRY_RUN
+		? (bin, args) => console.log(`[${ts()}] [DRY-RUN] exec: ${bin} ${JSON.stringify(args)}`)
+		: real_exec;
+	const mailer_send = DRY_RUN
+		? async (to, subject) => console.log(`[${ts()}] [DRY-RUN] send-mail: to=${to} subject=${JSON.stringify(subject)}`)
+		: real_mailer_send;
+	return { caller, users, mail_perm_store, exec, mailer_send };
 }
+
+async function run_action(def, params, ctx) {
 	return def.handler(params, ctx);
 }
 
@@ -104,11 +109,11 @@ app.post('/action', async (req, res) => {
 		return res.status(403).json({ status: 'denied', reason: 'Policy: auto-deny' });
 	}
 
-	const ctx = { caller: req.conduit_user, users, mail_perm_store, mailer_send };
+	const ctx = make_ctx(req.conduit_user);
 
 	if (def.policy === 'auto-accept') {
 		try {
-			const result = await run_action(def, action, params, ctx);
+			const result = await run_action(def, params, ctx);
 			return res.json({ status: 'accepted', result });
 		} catch (err) {
 			return res.status(500).json({ status: 'error', error: err.message });
@@ -142,10 +147,10 @@ app.post('/queue/:id/approve', async (req, res) => {
 	entry.resolved_by = req.conduit_user;
 	resolve(req.params.id, 'approved');
 
-	const ctx = { caller: entry.submitted_by, users, mail_perm_store, mailer_send };
+	const ctx = make_ctx(entry.submitted_by);
 	const def = actions[entry.action];
 	try {
-		const result = await run_action(def, entry.action, entry.params, ctx);
+		const result = await run_action(def, entry.params, ctx);
 		res.json({ status: 'approved', result });
 	} catch (err) {
 		res.status(500).json({ status: 'error', error: err.message });

server/mail_perms.mjs

@@ -23,7 +23,7 @@ export function load_mail_perms(file_path) {
 	}
 
 	function check(user, to, topic) {
-		return allowed.some(e => e.user === user && e.to === to && e.topic === topic);
+		return allowed.some(e => e.user === user && e.to === to && (e.topic === topic || e.topic === null));
 	}
 
 	function add(user, to, topic) {

server/secrets.mjs

@@ -1,23 +0,0 @@
-import { readFileSync } from "fs";
-
-export function load_secrets(file_path) {
-	if (!file_path) {
-		throw new Error("--secrets <path> is required");
-	}
-	let raw;
-	try {
-		raw = readFileSync(file_path, "utf8");
-	} catch (err) {
-		throw new Error(`Cannot read secrets file at ${file_path}: ${err.message}`);
-	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (err) {
-		throw new Error(`Secrets file is not valid JSON: ${err.message}`);
-	}
-	if (!parsed.users || typeof parsed.users !== 'object') {
-		throw new Error("Secrets file must have a top-level 'users' object");
-	}
-	return parsed; // callers destructure { users, smtp }
-}