@synoikia/core 0.1.0

package/dist/sandbox/index.js

@@ -0,0 +1,197 @@
+import ivm from 'isolated-vm';
+export const DEFAULT_LIMITS = {
+    timeoutMs: 10_000,
+    memoryMb: 64,
+    maxResultBytes: 64 * 1024,
+    maxLogBytes: 16 * 1024,
+};
+/** Thrown by a binding to surface a structured error (`err.code`) inside the sandbox. */
+export class BindingError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BindingError';
+    }
+}
+const RESERVED = new Set(['console', 'globalThis', '__syn']);
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Wall-clock budget that can be paused; fires `onExpire` once when it runs out. */
+class Budget {
+    onExpire;
+    remaining;
+    startedAt = 0;
+    paused = 0;
+    timer;
+    expired = false;
+    constructor(totalMs, onExpire) {
+        this.onExpire = onExpire;
+        this.remaining = totalMs;
+    }
+    start() {
+        this.startedAt = Date.now();
+        this.timer = setTimeout(() => {
+            this.expired = true;
+            this.onExpire();
+        }, this.remaining);
+    }
+    pause() {
+        if (this.paused++ > 0 || this.expired)
+            return;
+        clearTimeout(this.timer);
+        this.remaining -= Date.now() - this.startedAt;
+    }
+    resume() {
+        if (--this.paused > 0 || this.expired)
+            return;
+        this.start();
+    }
+    remainingMs() {
+        return this.paused > 0 ? this.remaining : Math.max(0, this.remaining - (Date.now() - this.startedAt));
+    }
+    stop() {
+        clearTimeout(this.timer);
+    }
+}
+// Runs inside the isolate, as its own script before the user's. Everything it holds on to — the host
+// references, the wrapper — lives in the closure, so user code (a separate script) can never name it.
+// It installs `console` and one frozen object per binding namespace, and removes `__syn` from the global.
+const prelude = (spec) => `(() => {
+  const call = globalThis.__syn.call;
+  const log = globalThis.__syn.log;
+  delete globalThis.__syn;
+  const stringify = JSON.stringify;
+  const parse = JSON.parse;
+  globalThis.console = Object.freeze({
+    log: (...a) => log.applySync(undefined, [stringify(a.map((x) => x === undefined ? null : x))]),
+  });
+  const bind = (ns, fn) => async (...args) => {
+    const raw = await call.apply(undefined, [ns, fn, stringify(args)], { result: { promise: true } });
+    const res = parse(raw);
+    if (res.ok) return res.value;
+    const err = new Error(res.error.message);
+    err.code = res.error.code;
+    throw err;
+  };
+  const spec = ${JSON.stringify(spec)};
+  for (const ns of Object.keys(spec)) {
+    const fns = {};
+    for (const fn of spec[ns]) fns[fn] = bind(ns, fn);
+    globalThis[ns] = Object.freeze(fns);
+  }
+})();`;
+function toJson(value) {
+    return JSON.stringify(value === undefined ? null : value);
+}
+export async function runInSandbox(run) {
+    const limits = { ...DEFAULT_LIMITS, ...run.limits };
+    const redact = run.redact ?? ((v) => v);
+    const logs = [];
+    let logBytes = 0;
+    const isolate = new ivm.Isolate({ memoryLimit: limits.memoryMb });
+    const budget = new Budget(limits.timeoutMs, () => {
+        if (!isolate.isDisposed)
+            isolate.dispose();
+    });
+    try {
+        const context = await isolate.createContext();
+        const jail = context.global;
+        await jail.set('globalThis', jail.derefInto());
+        const hostCall = async (ns, fn, argsJson) => {
+            // Own properties only: `constructor`, `__proto__` and friends are not bindings.
+            const fns = Object.hasOwn(run.bindings, ns) ? run.bindings[ns] : undefined;
+            const binding = fns && Object.hasOwn(fns, fn) ? fns[fn] : undefined;
+            if (!binding)
+                return toJson({ ok: false, error: { code: 'NOT_A_BINDING', message: `${ns}.${fn} is not available` } });
+            try {
+                const args = JSON.parse(argsJson);
+                return toJson({ ok: true, value: await binding(args, budget) });
+            }
+            catch (err) {
+                const code = err instanceof BindingError ? err.code : 'INTERNAL';
+                const message = err instanceof BindingError ? err.message : 'Internal error in binding';
+                return toJson({ ok: false, error: { code, message } });
+            }
+        };
+        const hostLog = (argsJson) => {
+            if (logBytes >= limits.maxLogBytes)
+                return;
+            let args;
+            try {
+                args = JSON.parse(argsJson);
+            }
+            catch {
+                args = ['[unprintable]'];
+            }
+            // Redact the values, then format: a JSON string of a secret has no key left to redact by.
+            const line = redact(args).map((x) => (typeof x === 'string' ? x : JSON.stringify(x))).join(' ');
+            const text = line.slice(0, limits.maxLogBytes - logBytes);
+            logBytes += text.length;
+            logs.push(text);
+        };
+        await jail.set('__syn', new ivm.ExternalCopy({}).copyInto());
+        const syn = (await jail.get('__syn'));
+        await syn.set('call', new ivm.Reference(hostCall));
+        await syn.set('log', new ivm.Reference(hostLog));
+        const spec = Object.fromEntries(Object.entries(run.bindings)
+            .filter(([ns]) => IDENT.test(ns) && !RESERVED.has(ns))
+            .map(([ns, fns]) => [ns, Object.keys(fns).filter((fn) => IDENT.test(fn))]));
+        await (await isolate.compileScript(prelude(spec))).run(context);
+        // The user's code is a separate script: it can't see the prelude's closure.
+        // Always settle with a JSON envelope so thrown errors keep their \`code\` across the boundary.
+        const source = `(async () => {\n${run.code}\n})().then(
+  (v) => JSON.stringify({ ok: true, value: v === undefined ? null : v }),
+  (e) => JSON.stringify({ ok: false, error: { code: typeof e?.code === 'string' ? e.code : 'CODE_ERROR', message: String(e?.message ?? e) } }),
+)`;
+        const script = await isolate.compileScript(source).catch((err) => {
+            throw new SandboxFailure('SYNTAX_ERROR', err.message);
+        });
+        budget.start();
+        const json = (await script.run(context, { promise: true, timeout: limits.timeoutMs }));
+        budget.stop();
+        const envelope = JSON.parse(json);
+        if (!envelope.ok)
+            return { ok: false, error: redact(envelope.error), logs };
+        // Redact before measuring: the preview of an oversized result is raw text, beyond key redaction.
+        const value = redact(envelope.value);
+        const valueJson = JSON.stringify(value);
+        const bytes = Buffer.byteLength(valueJson);
+        if (bytes > limits.maxResultBytes) {
+            const preview = Buffer.from(valueJson).subarray(0, limits.maxResultBytes).toString('utf8');
+            return { ok: true, value: { truncated: true, bytes, preview }, truncated: true, logs };
+        }
+        return { ok: true, value, truncated: false, logs };
+    }
+    catch (err) {
+        budget.stop();
+        return {
+            ok: false,
+            error: redact(classify(err, budget.expired, isolate)),
+            logs,
+        };
+    }
+    finally {
+        if (!isolate.isDisposed)
+            isolate.dispose();
+    }
+}
+class SandboxFailure extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function classify(err, expired, isolate) {
+    if (err instanceof SandboxFailure)
+        return { code: err.code, message: err.message };
+    const message = err instanceof Error ? err.message : String(err);
+    if (expired || /timed out/i.test(message))
+        return { code: 'TIMEOUT', message: 'Sandbox time limit exceeded' };
+    if (/memory limit/i.test(message) || isolate.isDisposed) {
+        return { code: 'MEMORY_LIMIT', message: 'Sandbox memory limit exceeded' };
+    }
+    // A synchronous throw at top level (the envelope catches everything asynchronous).
+    return { code: 'CODE_ERROR', message };
+}
+//# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+import type { Server } from 'node:http';
+import type { AppContext } from './app.js';
+export interface RunningServers {
+    mcp: {
+        server: Server;
+        port: number;
+    };
+    admin: {
+        server: Server;
+        port: number;
+    };
+    /** Stops accepting, then waits up to `graceMs` for open requests before cutting their connections. */
+    close(graceMs?: number): Promise<void>;
+}
+/** Starts the two listeners on separate ports (design §2.1). */
+export declare function startServers(ctx: AppContext): Promise<RunningServers>;

package/dist/server.js

@@ -0,0 +1,36 @@
+import { serve } from '@hono/node-server';
+import { createAdminApp } from './http/admin-app.js';
+import { createMcpApp } from './http/mcp-app.js';
+function listen(app, hostname, port) {
+    return new Promise((resolve, reject) => {
+        const server = serve({ fetch: app.fetch, hostname, port }, (info) => resolve({ server: server, port: info.port }));
+        server.once('error', reject);
+    });
+}
+function close(server, graceMs) {
+    return new Promise((resolve, reject) => {
+        const cut = setTimeout(() => server.closeAllConnections(), graceMs);
+        server.close((err) => {
+            clearTimeout(cut);
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+        server.closeIdleConnections();
+    });
+}
+/** Starts the two listeners on separate ports (design §2.1). */
+export async function startServers(ctx) {
+    const { config } = ctx;
+    const mcp = await listen(createMcpApp(ctx), config.MCP_HOST, config.MCP_PORT);
+    const admin = await listen(createAdminApp(ctx, { uiDir: config.ADMIN_UI_DIR }), config.ADMIN_HOST, config.ADMIN_PORT);
+    return {
+        mcp,
+        admin,
+        close: async (graceMs = 5000) => {
+            await Promise.all([close(mcp.server, graceMs), close(admin.server, graceMs)]);
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AASjD,SAAS,MAAM,CAAC,GAA8D,EAAE,QAAgB,EAAE,IAAY;IAC5G,OAAO,IAAI,OAAO,CAAmC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACvE,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,IAAiB,EAAE,EAAE,CAC/E,OAAO,CAAC,EAAE,MAAM,EAAE,MAAgB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAC7C,CAAC;QACZ,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,KAAK,CAAC,MAAc,EAAE,OAAe;IAC5C,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,EAAE,EAAE,OAAO,CAAC,CAAC;QACpE,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACnB,YAAY,CAAC,GAAG,CAAC,CAAC;YAClB,IAAI,GAAG;gBAAE,MAAM,CAAC,GAAG,CAAC,CAAC;;gBAChB,OAAO,EAAE,CAAC;QACjB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,oBAAoB,EAAE,CAAC;IAChC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAe;IAChD,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IACvB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACtH,OAAO;QACL,GAAG;QACH,KAAK;QACL,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,EAAE,EAAE;YAC9B,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAChF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/settings.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { Db } from './db/index.js';
+/** Global settings (design §8.2 "Settings"), one JSON document per section in the `settings` table. */
+export declare const SETTINGS_SCHEMAS: {
+    readonly security: z.ZodPrefault<z.ZodObject<{
+        requireTotp: z.ZodDefault<z.ZodBoolean>;
+        disableLocalLogin: z.ZodDefault<z.ZodBoolean>;
+        sessionIdleMinutes: z.ZodDefault<z.ZodNumber>;
+        sessionAbsoluteHours: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    readonly mcp: z.ZodPrefault<z.ZodObject<{
+        defaultAuthMode: z.ZodDefault<z.ZodEnum<{
+            external: "external";
+            bearer: "bearer";
+            oauth: "oauth";
+            "bearer+oauth": "bearer+oauth";
+        }>>;
+        allowDynamicRegistration: z.ZodDefault<z.ZodBoolean>;
+        cfAccess: z.ZodPrefault<z.ZodObject<{
+            teamDomain: z.ZodDefault<z.ZodString>;
+            aud: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+        trustedIdentityHeader: z.ZodDefault<z.ZodString>;
+        accessTokenTtlMinutes: z.ZodDefault<z.ZodNumber>;
+        refreshTokenTtlDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    readonly audit: z.ZodPrefault<z.ZodObject<{
+        retentionDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>;
+};
+export type SettingsSection = keyof typeof SETTINGS_SCHEMAS;
+export type Settings<S extends SettingsSection> = z.infer<(typeof SETTINGS_SCHEMAS)[S]>;
+export declare function isSettingsSection(name: string): name is SettingsSection;
+/** Stored settings are read leniently: a field a newer schema rejects falls back to its default. */
+export declare function getSettings<S extends SettingsSection>(db: Db, section: S): Settings<S>;
+/**
+ * Startup step: removes stored settings fields the current schema rejects, once (and warned about
+ * once) rather than on every read. Valid fields are left exactly as stored.
+ */
+export declare function normalizeStoredSettings(db: Db): string[];
+export declare function updateSettings<S extends SettingsSection>(db: Db, section: S, patch: unknown, actor?: {
+    userId?: string;
+}): Settings<S>;

package/dist/settings.js

@@ -0,0 +1,99 @@
+import { eq } from 'drizzle-orm';
+import { z } from 'zod';
+import { writeAudit } from './audit.js';
+import { settings } from './db/schema.js';
+import { ValidationError } from './errors.js';
+import { cleanStored, parseLeniently } from './lenient.js';
+/** Global settings (design §8.2 "Settings"), one JSON document per section in the `settings` table. */
+export const SETTINGS_SCHEMAS = {
+    security: z
+        .object({
+        /** Force every user to enroll TOTP at next login. */
+        requireTotp: z.boolean().default(false),
+        /** Only OIDC sign-in. Saving requires an OIDC-linked user; ADMIN_FORCE_LOCAL_LOGIN overrides. */
+        disableLocalLogin: z.boolean().default(false),
+        sessionIdleMinutes: z
+            .number()
+            .int()
+            .min(5)
+            .max(24 * 60)
+            .default(30),
+        sessionAbsoluteHours: z
+            .number()
+            .int()
+            .min(1)
+            .max(24 * 30)
+            .default(12),
+    })
+        .prefault({}),
+    mcp: z
+        .object({
+        defaultAuthMode: z.enum(['external', 'bearer', 'oauth', 'bearer+oauth']).default('bearer+oauth'),
+        allowDynamicRegistration: z.boolean().default(true),
+        /** Cloudflare Access JWT verification for `external` mode. */
+        cfAccess: z.object({ teamDomain: z.string().default(''), aud: z.string().default('') }).prefault({}),
+        /** Header set by an auth proxy (Authelia/Authentik) used only to attribute calls in `external` mode. */
+        trustedIdentityHeader: z.string().default(''),
+        accessTokenTtlMinutes: z
+            .number()
+            .int()
+            .min(5)
+            .max(24 * 60)
+            .default(60),
+        refreshTokenTtlDays: z.number().int().min(1).max(365).default(30),
+    })
+        .prefault({}),
+    audit: z
+        .object({
+        /** Unset = keep forever (design §10). */
+        retentionDays: z.number().int().min(7).nullable().default(null),
+    })
+        .prefault({}),
+};
+export function isSettingsSection(name) {
+    return Object.prototype.hasOwnProperty.call(SETTINGS_SCHEMAS, name);
+}
+/** Stored settings are read leniently: a field a newer schema rejects falls back to its default. */
+export function getSettings(db, section) {
+    const row = db.select().from(settings).where(eq(settings.key, section)).get();
+    return parseLeniently(SETTINGS_SCHEMAS[section], row?.value, `settings.${section}`);
+}
+/**
+ * Startup step: removes stored settings fields the current schema rejects, once (and warned about
+ * once) rather than on every read. Valid fields are left exactly as stored.
+ */
+export function normalizeStoredSettings(db) {
+    const changed = [];
+    for (const row of db.select().from(settings).all()) {
+        if (!isSettingsSection(row.key))
+            continue;
+        const { cleaned, dropped } = cleanStored(SETTINGS_SCHEMAS[row.key], row.value, `settings.${row.key}`);
+        if (!dropped.length)
+            continue;
+        db.update(settings).set({ value: cleaned }).where(eq(settings.key, row.key)).run();
+        changed.push(row.key);
+    }
+    return changed;
+}
+export function updateSettings(db, section, patch, actor = {}) {
+    const before = getSettings(db, section);
+    const parsed = SETTINGS_SCHEMAS[section].safeParse({ ...before, ...patch });
+    if (!parsed.success) {
+        throw new ValidationError('invalid_settings', 'Invalid settings', parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`));
+    }
+    db.transaction((tx) => {
+        tx.insert(settings)
+            .values({ key: section, value: parsed.data })
+            .onConflictDoUpdate({ target: settings.key, set: { value: parsed.data } })
+            .run();
+        writeAudit(tx, {
+            kind: 'config',
+            decision: 'settings_updated',
+            actorKind: 'user',
+            actorId: actor.userId,
+            detail: { section, before, after: parsed.data },
+        });
+    });
+    return parsed.data;
+}
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

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

package/dist/testing/index.d.ts

@@ -0,0 +1,73 @@
+import type { Manifest } from '@synoikia/plugin-sdk';
+import type { AppContext, AppOptions } from '../app.js';
+import { auditLog, operations, pendingApprovals, registryEntries } from '../db/schema.js';
+import type { AccessLevel } from '../gate/access.js';
+import type { SandboxResult } from '../sandbox/index.js';
+/**
+ * End-to-end harness for plugin packages (`@synoikia/core/testing`). A plugin's own test suite
+ * boots the real core on its built bundle, which runs as a permission-confined child exactly as in
+ * production, and drives it through the same `execute`/`search` path an MCP client uses. Core never
+ * names a plugin: each plugin brings its own fake upstream and its own assertions.
+ */
+export interface PluginHarnessOptions {
+    /** The plugin package directory (the one holding `manifest.json`); its entry must be built. */
+    pluginDir: string;
+    /** Connection config and secrets, as the admin portal would submit them. */
+    connection: Record<string, unknown>;
+    /** Endpoint slug; defaults to the plugin id. */
+    slug?: string;
+    /** Run a catalog/registry sync before returning (default true). */
+    sync?: boolean;
+    supervisor?: AppOptions['supervisor'];
+}
+/** An approval as the harness hands it to `onApproval`: decide it like the approval page would. */
+export interface HarnessApproval {
+    id: string;
+    operationKey: string;
+    /** The prompt the MCP client was shown. */
+    message: string;
+    /** The stored approval (operation, params, targets, diff, confirmation literal). */
+    pending: typeof pendingApprovals.$inferSelect;
+    /** Throws, as the approval page refuses it, when `confirm` doesn't match a typed confirmation. */
+    approve(confirm?: string): void;
+    deny(): void;
+}
+export interface ExecuteOptions {
+    /**
+     * Called for each approval the code triggers. Without it the caller can't be prompted, so a call
+     * that needs a human is denied. If it throws or leaves the approval open, the approval is denied
+     * and the error is kept in `approvalErrors`.
+     */
+    onApproval?: (approval: HarnessApproval) => void | Promise<void>;
+}
+export interface PluginHarness {
+    ctx: AppContext;
+    instanceId: string;
+    manifest: Manifest;
+    /** Errors thrown by `onApproval` handlers, oldest first. */
+    approvalErrors: unknown[];
+    execute(code: string, opts?: ExecuteOptions): Promise<SandboxResult>;
+    search(code: string): Promise<SandboxResult>;
+    setGroupLevel(group: string, level: AccessLevel): void;
+    /** The operation's own level; `null` makes it follow its group again. */
+    setOperationLevel(key: string, level: AccessLevel | null): void;
+    addRule(rule: {
+        operation: string;
+        match: unknown[];
+        reason: string;
+    }): {
+        id: string;
+    };
+    operation(key: string): typeof operations.$inferSelect;
+    operations(): (typeof operations.$inferSelect)[];
+    registry(): (typeof registryEntries.$inferSelect)[];
+    audit(filter?: {
+        operationKey?: string;
+    }): (typeof auditLog.$inferSelect)[];
+    instance(): ReturnType<AppContext['instances']['get']>;
+    /** Runs the plugin's `testConnection` in a throwaway child with this connection. */
+    testConnection(connection: Record<string, unknown>): Promise<unknown>;
+    syncNow(): ReturnType<AppContext['instances']['syncNow']>;
+    stop(): Promise<void>;
+}
+export declare function startPluginHarness(opts: PluginHarnessOptions): Promise<PluginHarness>;