@mininglamp-oss/cc-channel-octo 1.0.1-dev.60b73f3

package/dist/config.js

@@ -0,0 +1,332 @@
+/**
+ * Configuration loading.
+ *
+ * Two-layer, bot-first model:
+ *  - GLOBAL `~/.cc-channel-octo/config.json` — shared defaults + a `bots` list.
+ *    Never holds a botToken.
+ *  - PER-BOT `~/.cc-channel-octo/<id>/config.json` — that bot's botToken + any
+ *    overrides. Each bot is a self-contained subtree:
+ *      <baseDir>/<id>/{config.json, SOUL.md, data/, workspace/, memory/}
+ *  - `baseDir` is the directory containing the global config.json. Per-bot dirs
+ *    are DERIVED from `<baseDir>/<id>/…` (not separately configurable) so a bot
+ *    can never point its data outside its own subtree.
+ *
+ * env overrides still apply to the shared/global layer.
+ */
+import { readFileSync, existsSync, statSync, realpathSync } from 'node:fs';
+import { resolve as resolvePath, sep, dirname, join as pathJoin } from 'node:path';
+import { homedir } from 'node:os';
+import { isAllowedApiUrl } from './url-policy.js';
+/**
+ * Default global config path: `~/.cc-channel-octo/config.json`. This is the
+ * single, fixed production location (no env/CLI override). Tests pass an
+ * explicit path, which also sets `baseDir` to that file's directory.
+ */
+export const DEFAULT_CONFIG_PATH = pathJoin(homedir(), '.cc-channel-octo', 'config.json');
+function defaults() {
+    return {
+        botToken: '',
+        apiUrl: '',
+        // baseDir is set by loadConfig() from the config path's directory; the
+        // per-bot dirs below are DERIVED in resolveBotConfigs() as
+        // <baseDir>/<botId>/{workspace,data,memory}. Left empty here.
+        baseDir: '',
+        cwdBase: '',
+        cwd: '',
+        dataDir: '',
+        memoryBase: '',
+        sdk: {
+            // Q2: default to wildcard — operators tighten only when they need to.
+            allowedTools: '*',
+            permissionMode: 'bypassPermissions',
+            // #100: load project-scope settings so the SDK discovers skills symlinked
+            // into the session sandbox's .claude/skills/. Memory stays isolated via the
+            // inline settings.autoMemoryDirectory pin (flagSettings > projectSettings).
+            settingSources: ['project'],
+        },
+        rateLimit: {
+            maxPerMinute: 5,
+        },
+        context: {
+            maxContextChars: 6000,
+            historyLimit: 40,
+        },
+        maxResponseChars: 524_288, // 512 KB (Q32)
+        dispatchTimeoutMs: 300_000, // 5 min (#141)
+    };
+}
+function readConfigFile(configFilePath) {
+    if (!existsSync(configFilePath)) {
+        return {};
+    }
+    // Q12: Warn if config file is readable by group/others (contains botToken).
+    try {
+        const stat = statSync(configFilePath);
+        const mode = stat.mode & 0o777;
+        if (mode & 0o077) {
+            console.warn(`[cc-channel-octo] WARNING: ${configFilePath} has mode ${mode.toString(8)} — ` +
+                `secrets may be exposed to other users. Fix with: chmod 600 ${configFilePath}`);
+        }
+    }
+    catch {
+        // Best-effort check — don't block startup if stat fails.
+    }
+    const raw = readFileSync(configFilePath, 'utf-8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse config file ${configFilePath}: ${msg}`);
+    }
+    // Strip top-level keys starting with "_" (e.g. _comment).
+    const cleaned = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (!k.startsWith('_'))
+            cleaned[k] = v;
+    }
+    return cleaned;
+}
+function mergeConfig(base, override) {
+    return {
+        botToken: override.botToken ?? base.botToken,
+        apiUrl: override.apiUrl ?? base.apiUrl,
+        // baseDir + derived dirs are filled by loadConfig()/resolveBotConfigs(),
+        // not by config-file merge.
+        baseDir: base.baseDir,
+        cwdBase: base.cwdBase,
+        cwd: base.cwd,
+        dataDir: base.dataDir,
+        memoryBase: base.memoryBase,
+        groupConfigDir: override.groupConfigDir ?? base.groupConfigDir,
+        sdk: {
+            ...base.sdk,
+            ...(override.sdk ?? {}),
+        },
+        rateLimit: {
+            ...base.rateLimit,
+            ...(override.rateLimit ?? {}),
+        },
+        context: {
+            ...base.context,
+            ...(override.context ?? {}),
+        },
+        maxResponseChars: override.maxResponseChars ?? base.maxResponseChars,
+        dispatchTimeoutMs: override.dispatchTimeoutMs ?? base.dispatchTimeoutMs,
+        botBlocklist: override.botBlocklist ?? base.botBlocklist,
+        allowedBotUids: override.allowedBotUids ?? base.allowedBotUids,
+        mentionFreeGroups: override.mentionFreeGroups ?? base.mentionFreeGroups,
+        bots: override.bots ?? base.bots,
+    };
+}
+/**
+ * SSRF protection for apiUrl: implemented in url-policy.ts (isAllowedApiUrl).
+ * S6 fix: now rejects https://127.0.0.1 too — https doesn't make a private
+ * address safe (could be a self-signed mitmproxy).
+ */
+export function loadConfig(configPath) {
+    const path = configPath ?? DEFAULT_CONFIG_PATH;
+    // Migration aid: if the fixed global config is missing but a legacy
+    // ./config.json exists in the cwd, point the operator at the move rather than
+    // failing later with a cryptic "Missing required config: apiUrl".
+    if (configPath === undefined && !existsSync(path) && existsSync('./config.json')) {
+        throw new Error(`No config at ${path}, but ./config.json exists. The config location moved: ` +
+            `cc-channel-octo now loads ~/.cc-channel-octo/config.json (shared, no token) plus ` +
+            `~/.cc-channel-octo/<botId>/config.json (per-bot token). Move your settings there ` +
+            `(see config.example.json / config.bot.example.json).`);
+    }
+    const fileCfg = readConfigFile(path);
+    // Config comes ONLY from config.json (global + per-bot layers) — there is no
+    // environment-variable override path (#103). The sole exception that still
+    // *reads* the environment lives nowhere here: `sdk.anthropicBaseUrl` is set in
+    // config.json and forwarded to the SDK subprocess by agent-bridge.
+    const final = mergeConfig(defaults(), fileCfg);
+    // baseDir = the directory containing the global config.json. Every bot's
+    // subtree lives at <baseDir>/<botId>/…. resolveBotConfigs() derives the
+    // per-bot dirs from this.
+    final.baseDir = dirname(resolvePath(path));
+    // apiUrl is shared and required at the global layer (a per-bot config.json may
+    // still override it, re-checked per bot in resolveBotConfigs). botToken is NOT
+    // validated here — it lives in each bot's <id>/config.json.
+    if (!final.apiUrl) {
+        throw new Error('Missing required config: apiUrl (set CC_OCTO_API_URL or config.json)');
+    }
+    if (!isAllowedApiUrl(final.apiUrl)) {
+        throw new Error(`Unsafe apiUrl: ${final.apiUrl} — must be https:// or http://localhost/http://127.0.0.1 (SSRF protection)`);
+    }
+    // Q1: the gateway endpoint receives the Anthropic API key and all prompt /
+    // response content, so it gets the same SSRF policy as apiUrl.
+    if (final.sdk.anthropicBaseUrl && !isAllowedApiUrl(final.sdk.anthropicBaseUrl)) {
+        throw new Error(`Unsafe sdk.anthropicBaseUrl: ${final.sdk.anthropicBaseUrl} — must be https:// ` +
+            `or http://localhost/http://127.0.0.1 (SSRF protection)`);
+    }
+    return final;
+}
+/**
+ * Enforce that `groupConfigDir` (whose files are injected UNSANITIZED into the
+ * system prompt) is not the same as, nor nested under, the agent-writable
+ * `cwdBase`. Otherwise a user-driven agent could write its own future
+ * system-prompt instructions.
+ *
+ * Uses realpathSync.native for paths that exist (so symlinks can't dodge the
+ * boundary) and falls back to lexical resolve() for not-yet-created dirs.
+ */
+function assertGroupConfigDirOutsideCwd(cfg) {
+    if (!cfg.groupConfigDir)
+        return;
+    const cwdBase = cfg.cwdBase ?? cfg.cwd;
+    const cwdBaseResolved = canonicalize(cwdBase);
+    const groupDirResolved = canonicalize(cfg.groupConfigDir);
+    if (groupDirResolved === cwdBaseResolved || isPathInside(groupDirResolved, cwdBaseResolved)) {
+        throw new Error(`Unsafe groupConfigDir: ${cfg.groupConfigDir} is the same as or nested under ` +
+            `cwdBase (${cwdBase}). It must be operator-controlled and outside the ` +
+            `agent-writable sandbox, since its files are injected into the system prompt.`);
+    }
+}
+/** Resolve to a real path when it exists (defeats symlink dodges), else lexical. */
+function canonicalize(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return resolvePath(p);
+    }
+}
+/** True when `child` is strictly inside `parent` (both already resolved). */
+function isPathInside(child, parent) {
+    const parentWithSep = parent.endsWith(sep) ? parent : parent + sep;
+    return child.startsWith(parentWithSep);
+}
+/**
+ * v0.3 multi-bot: expand a loaded Config into one concrete Config per bot.
+ *
+ * - Single-bot (no `bots`): returns `[config]` with `botId` defaulted to
+ *   `default`, unchanged otherwise — fully backward compatible.
+ * - Multi-bot: returns one Config per `bots[]` entry. Each inherits the base
+ *   config and applies its overrides. To guarantee bots never share history,
+ *   cwd, or lock files, each bot's `dataDir` and `cwdBase` are namespaced by its
+ *   id UNLESS the entry sets them explicitly.
+ *
+ * Throws on missing/duplicate bot tokens or duplicate ids (fail fast at boot).
+ */
+/**
+ * Expand a loaded GLOBAL config into one concrete Config per bot.
+ *
+ * Two-layer, bot-first model:
+ * - Single-bot (no `bots`): one bot with id `default`. Its token/overrides come
+ *   from the global config and/or `<baseDir>/default/config.json`.
+ * - Multi-bot: one Config per `bots[]` entry (selected by `id`). For each, the
+ *   effective config is: global shared fields ⊕ inline `bots[]` fields ⊕
+ *   `<baseDir>/<id>/config.json` (per-dir file wins).
+ *
+ * Every bot's directories are DERIVED (never configurable):
+ *   data      = <baseDir>/<id>/data
+ *   workspace = <baseDir>/<id>/workspace   (cwdBase)
+ *   memory    = <baseDir>/<id>/memory
+ * and its personality from `<baseDir>/<id>/SOUL.md` (overrides systemPrompt).
+ *
+ * Throws on missing/duplicate tokens, duplicate ids, invalid id slugs, or unsafe
+ * apiUrl (fail fast at boot).
+ */
+export function resolveBotConfigs(config) {
+    // Single-bot: synthesize one entry with id "default".
+    const entries = config.bots && config.bots.length > 0
+        ? config.bots
+        : [{ id: 'default', botToken: config.botToken || undefined }];
+    const seenIds = new Set();
+    const seenTokens = new Set();
+    const resolvedBots = entries.map((bot, i) => {
+        const id = bot.id ?? `bot${i}`;
+        // The id becomes a path segment for the bot's subtree, so restrict it to a
+        // conservative slug — otherwise ids like "../ops" or "a/b" could escape or
+        // alias the intended directory, defeating isolation.
+        if (!/^[a-zA-Z0-9._-]+$/.test(id) || id === '.' || id === '..') {
+            throw new Error(`Bot "${id}": invalid id — use only letters, digits, dot, underscore, hyphen (no path separators)`);
+        }
+        if (seenIds.has(id)) {
+            throw new Error(`Duplicate bot id "${id}" — ids must be unique`);
+        }
+        seenIds.add(id);
+        // Derive the bot's self-contained subtree under baseDir.
+        const botRoot = pathJoin(config.baseDir, id);
+        const botDataDir = pathJoin(botRoot, 'data');
+        const botCwdBase = pathJoin(botRoot, 'workspace');
+        const botMemoryBase = pathJoin(botRoot, 'memory');
+        // #100: per-bot skills (<baseDir>/<id>/skills) + install-wide global skills
+        // (<baseDir>/skills). Symlinked into each session sandbox by skill-linker.
+        const botSkillsDir = pathJoin(botRoot, 'skills');
+        const globalSkillsDir = pathJoin(config.baseDir, 'skills');
+        // Per-bot config.json (in the bot's own subtree) is the highest-priority
+        // layer: global shared ⊕ inline bots[] entry ⊕ <baseDir>/<id>/config.json.
+        const perBotFile = readConfigFile(pathJoin(botRoot, 'config.json'));
+        const botToken = perBotFile.botToken ?? bot.botToken ?? '';
+        if (!botToken) {
+            throw new Error(`Bot "${id}": missing botToken — set it in ${pathJoin(botRoot, 'config.json')}`);
+        }
+        if (seenTokens.has(botToken)) {
+            throw new Error(`Duplicate botToken across bots — each bot needs a distinct token`);
+        }
+        seenTokens.add(botToken);
+        // openclaw-style SOUL.md in the bot's subtree overrides systemPrompt (which
+        // may come from the per-bot file, the inline entry, or the shared config).
+        const botSoul = loadSoul(botRoot);
+        const sharedSystemPrompt = config.sdk.systemPrompt;
+        const botSystemPrompt = botSoul ?? perBotFile.sdk?.systemPrompt ?? bot.systemPrompt ?? sharedSystemPrompt;
+        const apiUrl = perBotFile.apiUrl ?? bot.apiUrl ?? config.apiUrl;
+        const model = perBotFile.sdk?.model ?? bot.model ?? config.sdk.model;
+        const resolved = {
+            ...config,
+            bots: undefined, // a per-bot config is single-bot
+            botId: id,
+            botToken,
+            apiUrl,
+            baseDir: config.baseDir,
+            dataDir: botDataDir,
+            cwdBase: botCwdBase,
+            cwd: botCwdBase,
+            memoryBase: botMemoryBase,
+            skillsDir: botSkillsDir,
+            globalSkillsDir,
+            botBlocklist: perBotFile.botBlocklist ?? bot.botBlocklist ?? config.botBlocklist,
+            allowedBotUids: perBotFile.allowedBotUids ?? bot.allowedBotUids ?? config.allowedBotUids,
+            mentionFreeGroups: perBotFile.mentionFreeGroups ?? bot.mentionFreeGroups ?? config.mentionFreeGroups,
+            groupConfigDir: perBotFile.groupConfigDir ?? config.groupConfigDir,
+            sdk: {
+                ...config.sdk,
+                ...(perBotFile.sdk ?? {}),
+                ...(model !== undefined ? { model } : {}),
+                ...(botSystemPrompt !== undefined ? { systemPrompt: botSystemPrompt } : {}),
+            },
+        };
+        if (!isAllowedApiUrl(resolved.apiUrl)) {
+            throw new Error(`Bot "${id}": unsafe apiUrl ${resolved.apiUrl} (SSRF protection)`);
+        }
+        // GROUP.md trust boundary: groupConfigDir must not be the bot's writable cwd.
+        assertGroupConfigDirOutsideCwd(resolved);
+        return resolved;
+    });
+    return resolvedBots;
+}
+/**
+ * v1.1: openclaw-style per-bot personality. Read `<botRoot>/SOUL.md` if it
+ * exists and return its trimmed contents as the bot's "soul" (voice/stance/
+ * boundaries), to be composed into the agent system prompt. Mirrors openclaw's
+ * SOUL.md: a file you edit, not a config string. When the file is absent or
+ * empty, returns undefined so the caller falls back to the `systemPrompt`
+ * config string. Best-effort — a read error never blocks startup.
+ */
+export function loadSoul(botRoot) {
+    const path = pathJoin(botRoot, 'SOUL.md');
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const content = readFileSync(path, 'utf-8').trim();
+        return content.length > 0 ? content : undefined;
+    }
+    catch (err) {
+        console.warn(`[cc-channel-octo] WARNING: failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/cron-evaluator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * #115: Cron schedule evaluation — pure functions, no I/O.
+ *
+ * Supports two schedule forms:
+ *  - **5-field cron** `"minute hour dom month dow"` — each field is `*`, an
+ *    integer, `*` + `/step`, an `a-b` range, or a comma list of those. Standard
+ *    Unix semantics: dom/dow are OR'd when both are restricted (a task fires when
+ *    either matches), matching cron's historical behavior.
+ *  - **one-shot ISO datetime** `"2026-06-09T09:00:00Z"` — fires once at that
+ *    instant, then never again.
+ *
+ * Kept dependency-free (a tiny evaluator beats pulling a cron library for this).
+ *
+ * TIMEZONE: cron fields are matched against the gateway process's LOCAL time
+ * (`Date#getHours()` etc.), so `"0 9 * * *"` means 9am in the server's timezone.
+ * One-shot ISO datetimes are absolute instants (honor any offset/`Z` in the
+ * string). Set `TZ=...` on the process to control cron-field interpretation.
+ */
+/** A parsed 5-field cron expression: each field is the set of allowed values. */
+export interface ParsedCron {
+    minute: Set<number>;
+    hour: Set<number>;
+    dom: Set<number>;
+    month: Set<number>;
+    dow: Set<number>;
+    /** True when dom/dow were both restricted (affects OR semantics). */
+    domRestricted: boolean;
+    dowRestricted: boolean;
+}
+/** Parse a 5-field cron expression. Returns null when invalid. */
+export declare function parseCronExpression(expr: string): ParsedCron | null;
+/** True when `date` (local time) matches the parsed cron. */
+export declare function matchesCron(p: ParsedCron, date: Date): boolean;
+/** Heuristic: is this schedule a one-shot ISO datetime (vs a cron expr)? */
+export declare function isOneShotSchedule(schedule: string): boolean;
+/**
+ * Strictly parse a one-shot ISO-8601 datetime → Unix ms, or null if invalid.
+ *
+ * `new Date()` alone is too lenient (e.g. it rolls "2026-13-13T…" into a real
+ * but wrong instant instead of rejecting it). We additionally require the
+ * canonical shape via regex AND verify the authored wall-clock fields name a
+ * real calendar instant, so an out-of-range month/day/hour can't sneak through
+ * as a silently shifted time — for ALL zone forms (Z, ±hh:mm, or none).
+ */
+export declare function parseOneShot(schedule: string): number | null;
+/**
+ * Compute the next fire time (Unix ms) strictly after `fromMs`, or null when
+ * there is none (a past/invalid one-shot, or an impossible cron).
+ *
+ * - one-shot ISO: its instant if still in the future, else null.
+ * - cron: scan minute-by-minute from the next whole minute, up to ~366 days.
+ */
+export declare function computeNextRun(schedule: string, recurring: boolean, fromMs: number): number | null;

package/dist/cron-evaluator.js

@@ -0,0 +1,191 @@
+/**
+ * #115: Cron schedule evaluation — pure functions, no I/O.
+ *
+ * Supports two schedule forms:
+ *  - **5-field cron** `"minute hour dom month dow"` — each field is `*`, an
+ *    integer, `*` + `/step`, an `a-b` range, or a comma list of those. Standard
+ *    Unix semantics: dom/dow are OR'd when both are restricted (a task fires when
+ *    either matches), matching cron's historical behavior.
+ *  - **one-shot ISO datetime** `"2026-06-09T09:00:00Z"` — fires once at that
+ *    instant, then never again.
+ *
+ * Kept dependency-free (a tiny evaluator beats pulling a cron library for this).
+ *
+ * TIMEZONE: cron fields are matched against the gateway process's LOCAL time
+ * (`Date#getHours()` etc.), so `"0 9 * * *"` means 9am in the server's timezone.
+ * One-shot ISO datetimes are absolute instants (honor any offset/`Z` in the
+ * string). Set `TZ=...` on the process to control cron-field interpretation.
+ */
+const FIELD_RANGES = [
+    ['minute', 0, 59],
+    ['hour', 0, 23],
+    ['dom', 1, 31],
+    ['month', 1, 12],
+    ['dow', 0, 6], // 0 = Sunday
+];
+/** Expand one cron field into a set of allowed integers, or null if invalid. */
+function parseField(raw, min, max) {
+    const out = new Set();
+    for (const part of raw.split(',')) {
+        const seg = part.trim();
+        if (seg === '')
+            return null;
+        // step: "*/n" or "a-b/n" or "a/n"
+        let stepStr;
+        let rangeStr = seg;
+        const slash = seg.indexOf('/');
+        if (slash !== -1) {
+            rangeStr = seg.slice(0, slash);
+            stepStr = seg.slice(slash + 1);
+        }
+        let step = 1;
+        if (stepStr !== undefined) {
+            if (!/^\d+$/.test(stepStr))
+                return null;
+            step = Number(stepStr);
+            if (step < 1)
+                return null;
+        }
+        let lo;
+        let hi;
+        if (rangeStr === '*') {
+            lo = min;
+            hi = max;
+        }
+        else if (/^\d+$/.test(rangeStr)) {
+            lo = hi = Number(rangeStr);
+            // A bare number with a step (e.g. "5/10") means "from 5 to max, step".
+            if (stepStr !== undefined)
+                hi = max;
+        }
+        else {
+            const m = /^(\d+)-(\d+)$/.exec(rangeStr);
+            if (!m)
+                return null;
+            lo = Number(m[1]);
+            hi = Number(m[2]);
+        }
+        if (lo < min || hi > max || lo > hi)
+            return null;
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out.size > 0 ? out : null;
+}
+/** Parse a 5-field cron expression. Returns null when invalid. */
+export function parseCronExpression(expr) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5)
+        return null;
+    const sets = [];
+    for (let i = 0; i < 5; i++) {
+        const [, min, max] = FIELD_RANGES[i];
+        const set = parseField(fields[i], min, max);
+        if (!set)
+            return null;
+        sets.push(set);
+    }
+    return {
+        minute: sets[0],
+        hour: sets[1],
+        dom: sets[2],
+        month: sets[3],
+        dow: sets[4],
+        domRestricted: fields[2] !== '*',
+        dowRestricted: fields[4] !== '*',
+    };
+}
+/** True when `date` (local time) matches the parsed cron. */
+export function matchesCron(p, date) {
+    if (!p.minute.has(date.getMinutes()))
+        return false;
+    if (!p.hour.has(date.getHours()))
+        return false;
+    if (!p.month.has(date.getMonth() + 1))
+        return false;
+    const domOk = p.dom.has(date.getDate());
+    const dowOk = p.dow.has(date.getDay());
+    // Standard cron OR semantics: if BOTH dom and dow are restricted, match when
+    // EITHER matches; otherwise both (the unrestricted one is always true) must.
+    if (p.domRestricted && p.dowRestricted)
+        return domOk || dowOk;
+    return domOk && dowOk;
+}
+/** Heuristic: is this schedule a one-shot ISO datetime (vs a cron expr)? */
+export function isOneShotSchedule(schedule) {
+    // Cron exprs are space-separated fields; ISO datetimes contain 'T' and no spaces.
+    return schedule.includes('T') && !/\s/.test(schedule.trim());
+}
+/**
+ * Strictly parse a one-shot ISO-8601 datetime → Unix ms, or null if invalid.
+ *
+ * `new Date()` alone is too lenient (e.g. it rolls "2026-13-13T…" into a real
+ * but wrong instant instead of rejecting it). We additionally require the
+ * canonical shape via regex AND verify the authored wall-clock fields name a
+ * real calendar instant, so an out-of-range month/day/hour can't sneak through
+ * as a silently shifted time — for ALL zone forms (Z, ±hh:mm, or none).
+ */
+export function parseOneShot(schedule) {
+    const s = schedule.trim();
+    // YYYY-MM-DDThh:mm(:ss(.fff)?)? with optional Z or ±hh:mm offset.
+    const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})?$/.exec(s);
+    if (!m)
+        return null;
+    const t = new Date(s).getTime();
+    if (Number.isNaN(t))
+        return null;
+    // Reject lenient rollover. Calendar validity (is "Feb 31" a real date? is hour
+    // 25 valid?) is INDEPENDENT of the timezone, so validate the authored
+    // wall-clock fields with a zone-free UTC round-trip probe: if Date.UTC had to
+    // roll any field over, the rendered field won't match what the user wrote.
+    // This catches offset rollover (e.g. 2026-02-31T00:00:00+08:00) too — the old
+    // code skipped the check for numeric offsets and let it roll into March.
+    const yr = Number(m[1]);
+    const mo = Number(m[2]);
+    const day = Number(m[3]);
+    const hh = Number(m[4]);
+    const mm = Number(m[5]);
+    const ss = m[6] !== undefined ? Number(m[6]) : 0;
+    const probe = new Date(Date.UTC(yr, mo - 1, day, hh, mm, ss));
+    if (probe.getUTCFullYear() !== yr ||
+        probe.getUTCMonth() !== mo - 1 ||
+        probe.getUTCDate() !== day ||
+        probe.getUTCHours() !== hh ||
+        probe.getUTCMinutes() !== mm ||
+        probe.getUTCSeconds() !== ss) {
+        return null;
+    }
+    return t;
+}
+/**
+ * Compute the next fire time (Unix ms) strictly after `fromMs`, or null when
+ * there is none (a past/invalid one-shot, or an impossible cron).
+ *
+ * - one-shot ISO: its instant if still in the future, else null.
+ * - cron: scan minute-by-minute from the next whole minute, up to ~366 days.
+ */
+export function computeNextRun(schedule, recurring, fromMs) {
+    if (isOneShotSchedule(schedule)) {
+        const t = parseOneShot(schedule);
+        if (t === null)
+            return null;
+        return t > fromMs ? t : null;
+    }
+    const parsed = parseCronExpression(schedule);
+    if (!parsed)
+        return null;
+    void recurring; // cron exprs are inherently recurring; flag kept for symmetry
+    // Start at the next whole minute boundary after fromMs.
+    const start = new Date(fromMs);
+    start.setSeconds(0, 0);
+    start.setMinutes(start.getMinutes() + 1);
+    const MAX_MINUTES = 366 * 24 * 60;
+    const cursor = new Date(start);
+    for (let i = 0; i < MAX_MINUTES; i++) {
+        if (matchesCron(parsed, cursor))
+            return cursor.getTime();
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+    return null; // impossible schedule (e.g. Feb 31)
+}
+//# sourceMappingURL=cron-evaluator.js.map

package/dist/cron-evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-evaluator.js","sourceRoot":"","sources":["../src/cron-evaluator.ts"],"names":[],"mappings":"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"}

package/dist/cron-fire-marker.d.ts

@@ -0,0 +1,24 @@
+/**
+ * #115: Cron-fire authenticity marker.
+ *
+ * Synthetic cron messages bypass the group @mention gate. To stop a malicious
+ * group member from forging that bypass by putting `_cronFire: true` in a real
+ * message payload, the scheduler stamps each synthetic message with a secret
+ * nonce generated ONCE at process start, and the router accepts the bypass only
+ * when the nonce matches. The nonce never leaves the process (it is not derived
+ * from anything an attacker can observe), so an inbound WS message cannot carry
+ * the right value.
+ *
+ * Shared in its own tiny module so both `cron-scheduler` (stamp) and
+ * `session-router` (verify) depend on it without a circular import.
+ */
+/** Per-process secret. Regenerated each start — synthetic messages are
+ *  in-memory and short-lived, so a fresh nonce per process is fine. */
+export declare const CRON_FIRE_NONCE: string;
+/** Payload key carrying the nonce on a synthetic cron message. */
+export declare const CRON_FIRE_NONCE_KEY = "_cronFireNonce";
+/** True only for a genuine in-process cron fire (marker + matching nonce). */
+export declare function isAuthenticCronFire(payload: {
+    _cronFire?: unknown;
+    [k: string]: unknown;
+}): boolean;

package/dist/cron-fire-marker.js

@@ -0,0 +1,25 @@
+/**
+ * #115: Cron-fire authenticity marker.
+ *
+ * Synthetic cron messages bypass the group @mention gate. To stop a malicious
+ * group member from forging that bypass by putting `_cronFire: true` in a real
+ * message payload, the scheduler stamps each synthetic message with a secret
+ * nonce generated ONCE at process start, and the router accepts the bypass only
+ * when the nonce matches. The nonce never leaves the process (it is not derived
+ * from anything an attacker can observe), so an inbound WS message cannot carry
+ * the right value.
+ *
+ * Shared in its own tiny module so both `cron-scheduler` (stamp) and
+ * `session-router` (verify) depend on it without a circular import.
+ */
+import { randomBytes } from 'node:crypto';
+/** Per-process secret. Regenerated each start — synthetic messages are
+ *  in-memory and short-lived, so a fresh nonce per process is fine. */
+export const CRON_FIRE_NONCE = randomBytes(16).toString('hex');
+/** Payload key carrying the nonce on a synthetic cron message. */
+export const CRON_FIRE_NONCE_KEY = '_cronFireNonce';
+/** True only for a genuine in-process cron fire (marker + matching nonce). */
+export function isAuthenticCronFire(payload) {
+    return payload._cronFire === true && payload[CRON_FIRE_NONCE_KEY] === CRON_FIRE_NONCE;
+}
+//# sourceMappingURL=cron-fire-marker.js.map

package/dist/cron-fire-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-fire-marker.js","sourceRoot":"","sources":["../src/cron-fire-marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;uEACuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAE/D,kEAAkE;AAClE,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAEpD,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,OAAsD;IACxF,OAAO,OAAO,CAAC,SAAS,KAAK,IAAI,IAAI,OAAO,CAAC,mBAAmB,CAAC,KAAK,eAAe,CAAC;AACxF,CAAC"}