@synoikia/core 0.1.0

package/dist/instances/settings.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/** Per-instance runtime settings (design §8.2 "Instance Settings"), stored as JSON on `plugin_instances.settings`. */
+export declare const InstanceSettingsSchema: z.ZodPrefault<z.ZodObject<{
+    approvalTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    formElicitationApprovals: z.ZodDefault<z.ZodEnum<{
+        off: "off";
+        writes: "writes";
+    }>>;
+    executePerMinute: z.ZodDefault<z.ZodNumber>;
+    writesPerMinute: z.ZodDefault<z.ZodNumber>;
+    sandbox: z.ZodPrefault<z.ZodObject<{
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        memoryMb: z.ZodDefault<z.ZodNumber>;
+        maxResultBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    extraRedactKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    syncMaxAgeMs: z.ZodDefault<z.ZodNumber>;
+    memoryMb: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export type InstanceSettings = z.infer<typeof InstanceSettingsSchema>;
+export declare function parseInstanceSettings(raw: unknown): InstanceSettings;
+/** Stored instance settings, read leniently (a field a newer schema rejects falls back to its default). */
+export declare function readInstanceSettings(raw: unknown, label?: string): InstanceSettings;
+/** For the startup normalization: the stored settings with just the rejected fields removed. */
+export declare function cleanInstanceSettings(raw: unknown, label: string): {
+    value: {
+        approvalTimeoutMs: number;
+        formElicitationApprovals: "off" | "writes";
+        executePerMinute: number;
+        writesPerMinute: number;
+        sandbox: {
+            timeoutMs: number;
+            memoryMb: number;
+            maxResultBytes: number;
+        };
+        extraRedactKeys: string[];
+        syncMaxAgeMs: number;
+        memoryMb: number;
+    };
+    cleaned: unknown;
+    dropped: string[];
+};

package/dist/instances/settings.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { cleanStored, parseLeniently } from '../lenient.js';
+/** Per-instance runtime settings (design §8.2 "Instance Settings"), stored as JSON on `plugin_instances.settings`. */
+export const InstanceSettingsSchema = z
+    .object({
+    /** Unanswered approvals are auto-denied after this long (TN §3.3). */
+    approvalTimeoutMs: z
+        .number()
+        .int()
+        .min(10_000)
+        .max(24 * 60 * 60_000)
+        .default(15 * 60_000),
+    /**
+     * Let MCP clients that only support form prompts approve plain writes (never locked or
+     * typed-confirmation operations). Off by default: any client on this endpoint could then approve
+     * its own writes. URL prompts (a signed-in human on the approval page) always work.
+     */
+    formElicitationApprovals: z.enum(['off', 'writes']).default('off'),
+    /** `execute` and `search` runs per minute, per principal (design §5.2). */
+    executePerMinute: z.number().int().min(1).max(10_000).default(30),
+    writesPerMinute: z.number().int().min(1).max(10_000).default(10),
+    sandbox: z
+        .object({
+        timeoutMs: z.number().int().min(100).max(120_000).default(10_000),
+        memoryMb: z.number().int().min(8).max(1024).default(64),
+        maxResultBytes: z
+            .number()
+            .int()
+            .min(1024)
+            .max(4 * 1024 * 1024)
+            .default(64 * 1024),
+    })
+        .prefault({}),
+    extraRedactKeys: z.array(z.string().min(1)).default([]),
+    /** Re-sync the catalog on session start when the last sync is older than this (TN §5). */
+    syncMaxAgeMs: z
+        .number()
+        .int()
+        .min(60_000)
+        .max(7 * 24 * 60 * 60_000)
+        .default(60 * 60_000),
+    /** Plugin child heap limit (design §4.4). */
+    memoryMb: z.number().int().min(64).max(4096).default(256),
+})
+    .prefault({});
+export function parseInstanceSettings(raw) {
+    return InstanceSettingsSchema.parse(raw ?? {});
+}
+/** Stored instance settings, read leniently (a field a newer schema rejects falls back to its default). */
+export function readInstanceSettings(raw, label = 'instance settings') {
+    return parseLeniently(InstanceSettingsSchema, raw, label);
+}
+/** For the startup normalization: the stored settings with just the rejected fields removed. */
+export function cleanInstanceSettings(raw, label) {
+    return cleanStored(InstanceSettingsSchema, raw, label);
+}
+//# sourceMappingURL=settings.js.map

package/dist/instances/settings.js.map

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

package/dist/lenient.d.ts

@@ -0,0 +1,16 @@
+import type { z } from 'zod';
+/**
+ * Parses stored JSON (settings written by an earlier release) without letting one field the current
+ * schema no longer accepts take the whole feature down: each invalid field is dropped, so its default
+ * applies, and a warning names it. Input from requests is still validated strictly elsewhere.
+ */
+export declare function parseLeniently<S extends z.ZodType>(schema: S, raw: unknown, label: string, warn?: (message: string) => void): z.infer<S>;
+/**
+ * The lenient parse, plus the stored value with just the rejected fields removed (defaults are not
+ * written in, so a later release's new defaults still apply to fields nobody set).
+ */
+export declare function cleanStored<S extends z.ZodType>(schema: S, raw: unknown, label: string, warn?: (message: string) => void): {
+    value: z.infer<S>;
+    cleaned: unknown;
+    dropped: string[];
+};

package/dist/lenient.js

@@ -0,0 +1,51 @@
+/**
+ * Parses stored JSON (settings written by an earlier release) without letting one field the current
+ * schema no longer accepts take the whole feature down: each invalid field is dropped, so its default
+ * applies, and a warning names it. Input from requests is still validated strictly elsewhere.
+ */
+export function parseLeniently(schema, raw, label, warn = (m) => console.warn(`WARN ${m}`)) {
+    return cleanStored(schema, raw, label, warn).value;
+}
+/**
+ * The lenient parse, plus the stored value with just the rejected fields removed (defaults are not
+ * written in, so a later release's new defaults still apply to fields nobody set).
+ */
+export function cleanStored(schema, raw, label, warn = (m) => console.warn(`WARN ${m}`)) {
+    const cleaned = raw === null || raw === undefined ? {} : structuredClone(raw);
+    const dropped = [];
+    for (let attempt = 0; attempt < 20; attempt++) {
+        const parsed = schema.safeParse(cleaned);
+        if (parsed.success)
+            return { value: parsed.data, cleaned, dropped };
+        let progress = false;
+        for (const issue of parsed.error.issues) {
+            const path = issue.path.filter((p) => typeof p !== 'symbol');
+            if (path.length === 0 || !removeAt(cleaned, path))
+                continue;
+            warn(`${label}: ignoring stored ${path.join('.')} (${issue.message}); using the default`);
+            dropped.push(path.join('.'));
+            progress = true;
+        }
+        if (!progress)
+            break;
+    }
+    warn(`${label}: stored value is unusable; using defaults`);
+    return { value: schema.parse({}), cleaned: {}, dropped: [...dropped, '*'] };
+}
+function removeAt(root, path) {
+    let node = root;
+    for (const key of path.slice(0, -1)) {
+        if (!node || typeof node !== 'object')
+            return false;
+        node = node[key];
+    }
+    const last = path.at(-1);
+    if (!node || typeof node !== 'object' || !(last in node))
+        return false;
+    if (Array.isArray(node) && typeof last === 'number')
+        node.splice(last, 1);
+    else
+        delete node[last];
+    return true;
+}
+//# sourceMappingURL=lenient.js.map

package/dist/lenient.js.map

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

package/dist/lock.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A running server holds `DATA_DIR/server.lock` (pid and host). Offline operator commands such as
+ * `rotate-master-key` refuse to run while it is held: a live server keeps the old master key in memory
+ * and would write secrets under it after the rotation (design §7.1).
+ */
+export declare const LOCK_FILENAME = "server.lock";
+interface LockInfo {
+    pid: number;
+    host: string;
+    startedAt: string;
+}
+/**
+ * The live holder of the lock, or null if it is free or stale. A lock from another host (another
+ * container on the same volume) can't be checked from here, so it counts as held: only its pid on
+ * this host can be proven dead.
+ */
+export declare function lockHolder(dataDir: string): LockInfo | null;
+/**
+ * Takes the lock for this process; throws if another live server on this host holds it. A lock left
+ * by another host is taken over with a warning: a recreated container gets a new hostname, and a
+ * server that refused to start there would never start again. Returns the release.
+ */
+export declare function acquireServerLock(dataDir: string, warn?: (message: string) => void): () => void;
+/** For offline commands: throws while a server may be running on this data directory, unless forced. */
+export declare function assertServerStopped(dataDir: string, opts?: {
+    force?: boolean;
+}): void;
+export {};

package/dist/lock.js

@@ -0,0 +1,77 @@
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import path from 'node:path';
+/**
+ * A running server holds `DATA_DIR/server.lock` (pid and host). Offline operator commands such as
+ * `rotate-master-key` refuse to run while it is held: a live server keeps the old master key in memory
+ * and would write secrets under it after the rotation (design §7.1).
+ */
+export const LOCK_FILENAME = 'server.lock';
+const lockPath = (dataDir) => path.join(dataDir, LOCK_FILENAME);
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+};
+function readLock(dataDir) {
+    try {
+        const info = JSON.parse(readFileSync(lockPath(dataDir), 'utf8'));
+        return typeof info?.pid === 'number' && typeof info.host === 'string' ? info : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The live holder of the lock, or null if it is free or stale. A lock from another host (another
+ * container on the same volume) can't be checked from here, so it counts as held: only its pid on
+ * this host can be proven dead.
+ */
+export function lockHolder(dataDir) {
+    const info = readLock(dataDir);
+    if (!info || info.pid === process.pid)
+        return null;
+    if (info.host !== hostname())
+        return info;
+    return alive(info.pid) ? info : null;
+}
+/**
+ * Takes the lock for this process; throws if another live server on this host holds it. A lock left
+ * by another host is taken over with a warning: a recreated container gets a new hostname, and a
+ * server that refused to start there would never start again. Returns the release.
+ */
+export function acquireServerLock(dataDir, warn = (m) => console.warn(`WARN ${m}`)) {
+    const previous = readLock(dataDir);
+    if (previous && previous.pid !== process.pid) {
+        if (previous.host === hostname()) {
+            if (alive(previous.pid))
+                throw new Error(`Another server (pid ${previous.pid}) is using ${dataDir}`);
+        }
+        else {
+            warn(`${lockPath(dataDir)} was held by pid ${previous.pid} on host ${previous.host}; taking it over. ` +
+                'Two servers must never share a data directory.');
+        }
+    }
+    const info = { pid: process.pid, host: hostname(), startedAt: new Date().toISOString() };
+    writeFileSync(lockPath(dataDir), `${JSON.stringify(info)}\n`, { mode: 0o600 });
+    return () => {
+        if (readLock(dataDir)?.pid === process.pid && readLock(dataDir)?.host === hostname())
+            rmSync(lockPath(dataDir), { force: true });
+    };
+}
+/** For offline commands: throws while a server may be running on this data directory, unless forced. */
+export function assertServerStopped(dataDir, opts = {}) {
+    if (opts.force)
+        return;
+    const holder = lockHolder(dataDir);
+    if (!holder)
+        return;
+    const where = holder.host === hostname() ? `pid ${holder.pid}` : `pid ${holder.pid} on host ${holder.host}`;
+    throw new Error(`The server may be running (${where}, since ${holder.startedAt}); stop it first. ` +
+        `If it is really stopped, run again with --force (or delete ${lockPath(dataDir)}).`);
+}
+//# sourceMappingURL=lock.js.map

package/dist/lock.js.map

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

package/dist/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/main.js

@@ -0,0 +1,38 @@
+import { mkdirSync } from 'node:fs';
+import { createAppContext } from './app.js';
+import { loadConfig } from './config/env.js';
+import { acquireServerLock } from './lock.js';
+import { startServers } from './server.js';
+const config = loadConfig();
+mkdirSync(config.DATA_DIR, { recursive: true });
+const releaseLock = acquireServerLock(config.DATA_DIR);
+process.on('exit', releaseLock);
+const ctx = await createAppContext(config);
+for (const warning of ctx.warnings)
+    console.warn(`WARN ${warning}`);
+if (ctx.users.count() === 0)
+    console.log('No users yet: open the admin portal to create the first account.');
+await ctx.start();
+const servers = await startServers(ctx);
+console.log(`MCP listener on ${config.MCP_HOST}:${servers.mcp.port}`);
+console.log(`Admin listener on ${config.ADMIN_HOST}:${servers.admin.port}`);
+let stopping = false;
+const shutdown = (signal) => {
+    if (stopping)
+        return;
+    stopping = true;
+    console.log(`${signal} received, shutting down`);
+    // Drain first (approvals, MCP sessions, SSE), then close the listeners with a grace period, then stop
+    // plugins and the database; nothing here waits on a client that keeps its connection open.
+    ctx
+        .drain()
+        .then(() => servers.close())
+        .then(() => ctx.stop())
+        .then(() => process.exit(0), (err) => {
+        console.error(err);
+        process.exit(1);
+    });
+};
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;AAC5B,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAChD,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACvD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAChC,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAC3C,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,QAAQ;IAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAC;AACpE,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC;IAAE,OAAO,CAAC,GAAG,CAAC,kEAAkE,CAAC,CAAC;AAC7G,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;AAElB,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;AACxC,OAAO,CAAC,GAAG,CAAC,mBAAmB,MAAM,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;AACtE,OAAO,CAAC,GAAG,CAAC,qBAAqB,MAAM,CAAC,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAE5E,IAAI,QAAQ,GAAG,KAAK,CAAC;AACrB,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAE,EAAE;IAClC,IAAI,QAAQ;QAAE,OAAO;IACrB,QAAQ,GAAG,IAAI,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,0BAA0B,CAAC,CAAC;IACjD,sGAAsG;IACtG,2FAA2F;IAC3F,GAAG;SACA,KAAK,EAAE;SACP,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;SAC3B,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;SACtB,IAAI,CACH,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EACrB,CAAC,GAAY,EAAE,EAAE;QACf,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CACF,CAAC;AACN,CAAC,CAAC;AACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC"}

package/dist/maintenance.d.ts

@@ -0,0 +1,10 @@
+import type { AppContext } from './app.js';
+export interface HousekeepingResult {
+    sessions: number;
+    oauth: number;
+    approvalLinks: number;
+    preApprovalHits: number;
+    approvals: number;
+    audit: number;
+}
+export declare function runHousekeeping(ctx: AppContext): HousekeepingResult;

package/dist/maintenance.js

@@ -0,0 +1,48 @@
+import { and, lt, max, notInArray } from 'drizzle-orm';
+import { writeAudit } from './audit.js';
+import { auditLog, pendingApprovals, preApprovalHits, preApprovalRules } from './db/schema.js';
+import { getSettings } from './settings.js';
+/**
+ * Housekeeping (design §10): expired sessions, OAuth codes/tokens and approval links, rate-limit hits
+ * older than any rule's window, decided approvals past a week, and — only when an admin configured a
+ * retention — old audit rows. Runs hourly; every step is idempotent.
+ */
+const DAY = 24 * 60 * 60_000;
+export function runHousekeeping(ctx) {
+    const now = ctx.now();
+    // Keep hits for the longest rule window (default 1 h), so rate limits stay exact.
+    const longest = ctx.db
+        .select({ w: max(preApprovalRules.windowSeconds) })
+        .from(preApprovalRules)
+        .get()?.w ?? 3600;
+    const hitCutoff = new Date(now.getTime() - Math.max(longest, 3600) * 1000);
+    const hits = ctx.db.delete(preApprovalHits).where(lt(preApprovalHits.occurredAt, hitCutoff)).run().changes;
+    // Links cascade with their approval; approvals must outlive any link, and stay visible for a week.
+    const approvals = ctx.db
+        .delete(pendingApprovals)
+        .where(and(lt(pendingApprovals.requestedAt, new Date(now.getTime() - 7 * DAY)), notInArray(pendingApprovals.status, ['pending'])))
+        .run().changes;
+    let audit = 0;
+    const { retentionDays } = getSettings(ctx.db, 'audit');
+    if (retentionDays) {
+        const cutoff = new Date(now.getTime() - retentionDays * DAY);
+        audit = ctx.db.delete(auditLog).where(lt(auditLog.at, cutoff)).run().changes;
+        if (audit > 0) {
+            writeAudit(ctx.db, {
+                kind: 'config',
+                decision: 'audit_purged',
+                actorKind: 'system',
+                detail: { rows: audit, before: cutoff.toISOString(), retentionDays },
+            }, now);
+        }
+    }
+    return {
+        sessions: ctx.sessions.purgeExpired(),
+        oauth: ctx.oauth.purgeExpired(),
+        approvalLinks: ctx.links.purgeExpired(),
+        preApprovalHits: hits,
+        approvals,
+        audit,
+    };
+}
+//# sourceMappingURL=maintenance.js.map

package/dist/maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.js","sourceRoot":"","sources":["../src/maintenance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;GAIG;AAEH,MAAM,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;AAW7B,MAAM,UAAU,eAAe,CAAC,GAAe;IAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC;IAEtB,kFAAkF;IAClF,MAAM,OAAO,GACX,GAAG,CAAC,EAAE;SACH,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC;SAClD,IAAI,CAAC,gBAAgB,CAAC;SACtB,GAAG,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC;IACtB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3E,MAAM,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,eAAe,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;IAE3G,mGAAmG;IACnG,MAAM,SAAS,GAAG,GAAG,CAAC,EAAE;SACrB,MAAM,CAAC,gBAAgB,CAAC;SACxB,KAAK,CACJ,GAAG,CACD,EAAE,CAAC,gBAAgB,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,EACnE,UAAU,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,CACjD,CACF;SACA,GAAG,EAAE,CAAC,OAAO,CAAC;IAEjB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,EAAE,aAAa,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACvD,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,aAAa,GAAG,GAAG,CAAC,CAAC;QAC7D,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;QAC7E,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,UAAU,CACR,GAAG,CAAC,EAAE,EACN;gBACE,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,cAAc;gBACxB,SAAS,EAAE,QAAQ;gBACnB,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE;aACrE,EACD,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,YAAY,EAAE;QACrC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE;QAC/B,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE;QACvC,eAAe,EAAE,IAAI;QACrB,SAAS;QACT,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/notify/service.d.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import type { SecretBox } from '../crypto/index.js';
+import type { Db } from '../db/index.js';
+import type { CoreEvents } from '../events.js';
+/**
+ * Notification channels (design §9): ntfy and signed webhooks, subscribed to core events and
+ * optionally filtered by instance. Informational only: approvals happen in the MCP client (§5.3).
+ * Payloads carry summaries, never raw params or secrets.
+ */
+export declare const NOTIFY_EVENTS: readonly ["instance.error", "instance.recovered", "plugin.crashed", "sync.failed", "sync.pending_review", "auth.lockout"];
+export type NotifyEvent = (typeof NOTIFY_EVENTS)[number];
+export declare const ChannelInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"ntfy">;
+    name: z.ZodString;
+    config: z.ZodObject<{
+        server: z.ZodDefault<z.ZodURL>;
+        topic: z.ZodString;
+    }, z.core.$strip>;
+    secrets: z.ZodDefault<z.ZodObject<{
+        token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    events: z.ZodArray<z.ZodEnum<{
+        "plugin.crashed": "plugin.crashed";
+        "sync.failed": "sync.failed";
+        "auth.lockout": "auth.lockout";
+        "instance.error": "instance.error";
+        "instance.recovered": "instance.recovered";
+        "sync.pending_review": "sync.pending_review";
+    }>>;
+    instanceFilter: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"webhook">;
+    name: z.ZodString;
+    config: z.ZodObject<{
+        url: z.ZodURL;
+    }, z.core.$strip>;
+    secrets: z.ZodDefault<z.ZodObject<{
+        hmacSecret: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        headers: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    }, z.core.$strip>>;
+    events: z.ZodArray<z.ZodEnum<{
+        "plugin.crashed": "plugin.crashed";
+        "sync.failed": "sync.failed";
+        "auth.lockout": "auth.lockout";
+        "instance.error": "instance.error";
+        "instance.recovered": "instance.recovered";
+        "sync.pending_review": "sync.pending_review";
+    }>>;
+    instanceFilter: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>], "kind">;
+export interface Notification {
+    event: NotifyEvent;
+    instance?: {
+        id: string;
+        slug: string;
+    };
+    title: string;
+    message: string;
+    data: Record<string, unknown>;
+}
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+export declare class NotifierService {
+    private readonly db;
+    private readonly box;
+    private readonly opts;
+    private readonly lastStatus;
+    constructor(db: Db, box: SecretBox, opts?: {
+        fetch?: FetchLike;
+        retryDelaysMs?: number[];
+        now?: () => Date;
+    });
+    private secretsOf;
+    private publicRow;
+    list(): {
+        events: ("plugin.crashed" | "sync.failed" | "auth.lockout" | "instance.error" | "instance.recovered" | "sync.pending_review")[];
+        secretsEnc: undefined;
+        secrets: {
+            hmacSecret?: {
+                set: boolean;
+            } | undefined;
+            headers?: {
+                set: boolean;
+            } | undefined;
+            token?: {
+                set: boolean;
+            } | undefined;
+        };
+        id: string;
+        name: string;
+        kind: "ntfy" | "webhook";
+        enabled: boolean;
+        config: unknown;
+        instanceFilter: string[] | null;
+        lastSentAt: Date | null;
+        lastError: string | null;
+    }[];
+    private mergeSecrets;
+    save(raw: unknown, opts?: {
+        id?: string;
+        actor?: {
+            userId?: string;
+        };
+    }): {
+        events: ("plugin.crashed" | "sync.failed" | "auth.lockout" | "instance.error" | "instance.recovered" | "sync.pending_review")[];
+        secretsEnc: undefined;
+        secrets: {
+            hmacSecret?: {
+                set: boolean;
+            } | undefined;
+            headers?: {
+                set: boolean;
+            } | undefined;
+            token?: {
+                set: boolean;
+            } | undefined;
+        };
+        id: string;
+        name: string;
+        kind: "ntfy" | "webhook";
+        enabled: boolean;
+        config: unknown;
+        instanceFilter: string[] | null;
+        lastSentAt: Date | null;
+        lastError: string | null;
+    };
+    remove(id: string, actor?: {
+        userId?: string;
+    }): void;
+    /** Sends a test message to one channel, bypassing its event filter. */
+    test(id: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Wires channels to the event bus. Returns an unsubscribe function. */
+    subscribe(events: CoreEvents): () => void;
+    /** Fans a notification out to every enabled channel subscribed to its event (and instance). */
+    dispatch(n: Notification): Promise<void>;
+    private deliver;
+}