@synoikia/core 0.1.0

package/dist/plugins/minisign.js

@@ -0,0 +1,49 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+export class MinisignError extends Error {
+}
+/** Minisign prints key ids as a little-endian u64. */
+const keyIdHex = (bytes) => Buffer.from(bytes).reverse().toString('hex').toUpperCase();
+/** Accepts the bare base64 key line or a whole `.pub` file (with its untrusted comment). */
+export function parsePublicKey(text) {
+    const line = text
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('untrusted comment:'))[0];
+    const raw = line && /^[A-Za-z0-9+/]+={0,2}$/.test(line) ? Buffer.from(line, 'base64') : Buffer.alloc(0);
+    if (raw.length !== 42 || raw.subarray(0, 2).toString('latin1') !== 'Ed') {
+        throw new MinisignError('Not a minisign Ed25519 public key');
+    }
+    const key = createPublicKey({
+        key: { kty: 'OKP', crv: 'Ed25519', x: raw.subarray(10).toString('base64url') },
+        format: 'jwk',
+    });
+    return { keyId: keyIdHex(raw.subarray(2, 10)), key, base64: raw.toString('base64') };
+}
+/** Throws MinisignError unless `signature` is a valid minisign signature of `data` by `publicKey`. */
+export function verifySignature(data, signature, publicKey) {
+    const lines = signature.split(/\r?\n/).map((l) => l.trim());
+    if (lines.length < 4 || !lines[0].startsWith('untrusted comment:') || !lines[2].startsWith('trusted comment: ')) {
+        throw new MinisignError('Malformed minisign signature');
+    }
+    const sig = Buffer.from(lines[1], 'base64');
+    const globalSig = Buffer.from(lines[3], 'base64');
+    if (sig.length !== 74 || globalSig.length !== 64)
+        throw new MinisignError('Malformed minisign signature');
+    const alg = sig.subarray(0, 2).toString('latin1');
+    if (alg !== 'Ed' && alg !== 'ED')
+        throw new MinisignError(`Unsupported signature algorithm ${alg}`);
+    const keyId = keyIdHex(sig.subarray(2, 10));
+    if (keyId !== publicKey.keyId) {
+        throw new MinisignError(`Signed by key ${keyId}, expected ${publicKey.keyId}`);
+    }
+    const signed = alg === 'ED' ? createHash('blake2b512').update(data).digest() : data;
+    const bare = sig.subarray(10);
+    if (!verify(null, signed, publicKey.key, bare))
+        throw new MinisignError('Signature does not match the file');
+    const trustedComment = lines[2].slice('trusted comment: '.length);
+    if (!verify(null, Buffer.concat([bare, Buffer.from(trustedComment, 'utf8')]), publicKey.key, globalSig)) {
+        throw new MinisignError('Trusted comment signature is invalid');
+    }
+    return { keyId, prehashed: alg === 'ED', trustedComment };
+}
+//# sourceMappingURL=minisign.js.map

package/dist/plugins/minisign.js.map

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

package/dist/plugins/process.d.ts

@@ -0,0 +1,55 @@
+import { EventEmitter } from 'node:events';
+import type { ErrorCode, PluginHandlers, RpcMethod } from '@synoikia/plugin-sdk';
+/**
+ * One plugin child process and the core side of its JSON-RPC-over-IPC channel (design §3.3, §4.4).
+ * Every result is validated before it is returned: plugin output is untrusted.
+ */
+export declare class PluginRpcError extends Error {
+    readonly code: ErrorCode;
+    readonly data?: unknown | undefined;
+    constructor(code: ErrorCode, message: string, data?: unknown | undefined);
+}
+/** The child is not running (never started, crashed, or stopped). Callers surface `PluginUnavailable`. */
+export declare class PluginUnavailableError extends Error {
+    constructor(message?: string);
+}
+export declare class PluginTimeoutError extends Error {
+    constructor(method: string, ms: number);
+}
+/** The plugin answered with something that violates the contract. */
+export declare class PluginProtocolError extends Error {
+    constructor(method: string, detail: string);
+}
+type Params<M extends RpcMethod> = Parameters<NonNullable<PluginHandlers[M]>>[0];
+type Result<M extends RpcMethod> = Awaited<ReturnType<NonNullable<PluginHandlers[M]>>>;
+export interface SpawnOptions {
+    /** Plugin package directory; the only path the child may read. */
+    dir: string;
+    entry: string;
+    instanceId: string;
+    memoryMb?: number;
+    defaultTimeoutMs?: number;
+}
+export interface PluginProcessEvents {
+    exit: [code: number | null, signal: NodeJS.Signals | null];
+    log: [level: string, message: string];
+    catalogChanged: [reason?: string];
+}
+export declare class PluginProcess extends EventEmitter<PluginProcessEvents> {
+    private readonly opts;
+    private child?;
+    private nextId;
+    private readonly pending;
+    private exited;
+    constructor(opts: SpawnOptions);
+    get running(): boolean;
+    get pid(): number | undefined;
+    /** Forks the entry under the Node permission model: read-only access to its own dir, nothing else. */
+    start(): void;
+    call<M extends RpcMethod>(method: M, params?: Params<M>, timeoutMs?: number): Promise<Result<M>>;
+    /** Graceful stop: `shutdown` RPC, then SIGKILL if the child hasn't exited within `graceMs`. */
+    stop(graceMs?: number): Promise<void>;
+    kill(): void;
+    private onMessage;
+}
+export {};

package/dist/plugins/process.js

@@ -0,0 +1,162 @@
+import { fork } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import path from 'node:path';
+import { GuideSchema, OptionSchema, PrepareWriteResultSchema, RegistryEntrySchema, ResolvedTargetSchema, ResolveOperationResultSchema, SummarizeResultSchema, SyncCatalogResultSchema, TestConnectionResultSchema, } from '@synoikia/plugin-sdk';
+import { z } from 'zod';
+/**
+ * One plugin child process and the core side of its JSON-RPC-over-IPC channel (design §3.3, §4.4).
+ * Every result is validated before it is returned: plugin output is untrusted.
+ */
+export class PluginRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'PluginRpcError';
+    }
+}
+/** The child is not running (never started, crashed, or stopped). Callers surface `PluginUnavailable`. */
+export class PluginUnavailableError extends Error {
+    constructor(message = 'Plugin process is not available') {
+        super(message);
+        this.name = 'PluginUnavailableError';
+    }
+}
+export class PluginTimeoutError extends Error {
+    constructor(method, ms) {
+        super(`Plugin did not answer ${method} within ${ms} ms`);
+        this.name = 'PluginTimeoutError';
+    }
+}
+/** The plugin answered with something that violates the contract. */
+export class PluginProtocolError extends Error {
+    constructor(method, detail) {
+        super(`Invalid ${method} result from plugin: ${detail}`);
+        this.name = 'PluginProtocolError';
+    }
+}
+const nullish = z.unknown().transform(() => null);
+const RESULT_SCHEMAS = {
+    init: nullish,
+    testConnection: TestConnectionResultSchema,
+    getUpstreamVersion: z.string().min(1),
+    syncCatalog: SyncCatalogResultSchema,
+    syncRegistry: z.array(RegistryEntrySchema),
+    resolveOperation: ResolveOperationResultSchema,
+    resolveTargets: z.array(ResolvedTargetSchema),
+    summarize: SummarizeResultSchema,
+    prepareWrite: PrepareWriteResultSchema,
+    invoke: z.unknown(),
+    optionsFor: z.array(OptionSchema),
+    getGuide: GuideSchema,
+    shutdown: nullish,
+};
+export class PluginProcess extends EventEmitter {
+    opts;
+    child;
+    nextId = 1;
+    pending = new Map();
+    exited = false;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+    }
+    get running() {
+        return !!this.child && !this.exited;
+    }
+    get pid() {
+        return this.child?.pid;
+    }
+    /** Forks the entry under the Node permission model: read-only access to its own dir, nothing else. */
+    start() {
+        if (this.child)
+            throw new Error('Plugin process already started');
+        const dir = path.resolve(this.opts.dir);
+        this.child = fork(path.resolve(dir, this.opts.entry), [], {
+            cwd: dir,
+            execArgv: ['--permission', `--allow-fs-read=${dir}`, `--max-old-space-size=${this.opts.memoryMb ?? 256}`],
+            // Scrubbed environment: no MASTER_KEY, DB paths or admin config ever reach the plugin.
+            env: { NODE_ENV: process.env.NODE_ENV ?? 'production', PLUGIN_INSTANCE_ID: this.opts.instanceId },
+            stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+            serialization: 'json',
+        });
+        this.child.stdout?.on('data', (d) => this.emit('log', 'info', d.toString().trimEnd()));
+        this.child.stderr?.on('data', (d) => this.emit('log', 'error', d.toString().trimEnd()));
+        this.child.on('message', (msg) => this.onMessage(msg));
+        this.child.on('error', (err) => this.emit('log', 'error', `plugin process error: ${err.message}`));
+        this.child.on('exit', (code, signal) => {
+            this.exited = true;
+            for (const p of this.pending.values()) {
+                clearTimeout(p.timer);
+                p.reject(new PluginUnavailableError(`Plugin exited (${signal ?? code}) during ${p.method}`));
+            }
+            this.pending.clear();
+            this.emit('exit', code, signal);
+        });
+    }
+    async call(method, params, timeoutMs) {
+        const child = this.child;
+        if (!child || this.exited || !child.connected)
+            throw new PluginUnavailableError();
+        const id = this.nextId++;
+        const ms = timeoutMs ?? this.opts.defaultTimeoutMs ?? 30_000;
+        const raw = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new PluginTimeoutError(method, ms));
+            }, ms);
+            this.pending.set(id, { method, resolve, reject, timer });
+            child.send({ jsonrpc: '2.0', id, method, params }, (err) => {
+                if (!err)
+                    return;
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(new PluginUnavailableError(`Could not send ${method}: ${err.message}`));
+            });
+        });
+        const parsed = RESULT_SCHEMAS[method].safeParse(raw);
+        if (!parsed.success) {
+            throw new PluginProtocolError(method, parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; '));
+        }
+        return parsed.data;
+    }
+    /** Graceful stop: `shutdown` RPC, then SIGKILL if the child hasn't exited within `graceMs`. */
+    async stop(graceMs = 2000) {
+        const child = this.child;
+        if (!child || this.exited)
+            return;
+        const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+        this.call('shutdown', undefined, graceMs).catch(() => undefined);
+        const killTimer = setTimeout(() => child.kill('SIGKILL'), graceMs);
+        await exited;
+        clearTimeout(killTimer);
+    }
+    kill() {
+        this.child?.kill('SIGKILL');
+    }
+    onMessage(msg) {
+        if (typeof msg !== 'object' || msg === null || msg.jsonrpc !== '2.0')
+            return;
+        if ('id' in msg && typeof msg.id === 'number') {
+            const pending = this.pending.get(msg.id);
+            if (!pending)
+                return;
+            this.pending.delete(msg.id);
+            clearTimeout(pending.timer);
+            const res = msg;
+            if ('error' in res)
+                pending.reject(new PluginRpcError(res.error.code, res.error.message, res.error.data));
+            else
+                pending.resolve(res.result);
+            return;
+        }
+        const note = msg;
+        if (note.method === 'log')
+            this.emit('log', note.params.level, note.params.message);
+        else if (note.method === 'catalogChanged')
+            this.emit('catalogChanged', note.params?.reason);
+    }
+}
+//# sourceMappingURL=process.js.map

package/dist/plugins/process.js.map

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

package/dist/plugins/repos.d.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import type { Db } from '../db/index.js';
+export declare const IndexSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    name: z.ZodString;
+    homepage: z.ZodOptional<z.ZodString>;
+    publicKey: z.ZodOptional<z.ZodString>;
+    plugins: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        versions: z.ZodArray<z.ZodObject<{
+            version: z.ZodString;
+            sdk: z.ZodString;
+            minCoreVersion: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            sha256: z.ZodString;
+            signature: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RepoIndex = z.infer<typeof IndexSchema>;
+export declare const AddRepoSchema: z.ZodObject<{
+    url: z.ZodURL;
+    signingMode: z.ZodEnum<{
+        signed: "signed";
+        unsigned: "unsigned";
+    }>;
+    confirmPublicKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const InstallSchema: z.ZodObject<{
+    repoId: z.ZodString;
+    pluginId: z.ZodString;
+    version: z.ZodString;
+    confirm: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FetchBytes = (url: string, init?: {
+    signal?: AbortSignal;
+    redirect?: 'manual';
+}) => Promise<Response>;
+type Actor = {
+    userId?: string;
+};
+export interface RepoServiceOptions {
+    db: Db;
+    dataDir: string;
+    fetch?: FetchBytes;
+    /** Only for tests and lab mirrors: allow http:// index and tarball URLs. */
+    allowHttp?: boolean;
+    now?: () => Date;
+    /** Re-scan plugin directories into the registry. */
+    discover: () => unknown;
+    /** Stop every instance of a plugin row before its files change. */
+    stopPlugin: (pluginRowId: string) => Promise<void>;
+    /** Start (and resync) every servable instance of a plugin row. */
+    startPlugin: (pluginRowId: string) => Promise<void>;
+}
+/** The parts of a manifest that change what a plugin may do; an update touching them needs review. */
+export declare function permissionChanges(before: unknown, after: unknown): string[];
+/**
+ * Replaces `target` with `next`, keeping the previous copy at `backup` until the swap succeeded. If
+ * moving `next` in fails, the previous copy is moved back, so a failed update never leaves no plugin.
+ */
+export declare function swapDirectory(next: string, target: string, backup: string, rename?: (from: string, to: string) => void): void;
+export declare class PluginRepoService {
+    private readonly opts;
+    private readonly installing;
+    constructor(opts: RepoServiceOptions);
+    private get db();
+    private now;
+    private checkUrl;
+    private download;
+    private fetchIndex;
+    private keyOf;
+    private repoRow;
+    private publicRepo;
+    list(): {
+        id: string;
+        url: string;
+        name: string | null;
+        signingMode: "signed" | "unsigned";
+        publicKey: string | null;
+        keyId: string | null;
+        keyStatus: "ok" | "key_changed";
+        /** When the key changed: the new key awaiting confirmation. */
+        offeredKey: {
+            publicKey: string;
+            keyId: string;
+        } | null;
+        pluginCount: number;
+        lastFetchedAt: Date | null;
+        lastFetchError: string | null;
+    }[];
+    /**
+     * Adds a repository. Signed repos take two calls: the first answers 409 `confirm_key` with the key
+     * id, the second repeats the request with `confirmKeyId` once the admin has checked it out of band.
+     */
+    add(raw: unknown, actor?: Actor): Promise<{
+        id: string;
+        url: string;
+        name: string | null;
+        signingMode: "signed" | "unsigned";
+        publicKey: string | null;
+        keyId: string | null;
+        keyStatus: "ok" | "key_changed";
+        /** When the key changed: the new key awaiting confirmation. */
+        offeredKey: {
+            publicKey: string;
+            keyId: string;
+        } | null;
+        pluginCount: number;
+        lastFetchedAt: Date | null;
+        lastFetchError: string | null;
+    }>;
+    /** Re-reads the index. A changed signing key blocks installs until re-confirmed. */
+    refresh(id: string): Promise<{
+        id: string;
+        url: string;
+        name: string | null;
+        signingMode: "signed" | "unsigned";
+        publicKey: string | null;
+        keyId: string | null;
+        keyStatus: "ok" | "key_changed";
+        /** When the key changed: the new key awaiting confirmation. */
+        offeredKey: {
+            publicKey: string;
+            keyId: string;
+        } | null;
+        pluginCount: number;
+        lastFetchedAt: Date | null;
+        lastFetchError: string | null;
+    }>;
+    /** Daily refresh (design §10). Failures are recorded on the row, never thrown. */
+    refreshStale(maxAgeMs?: number): Promise<void>;
+    /** Pins the key a refreshed index now offers, after the admin checked it against the publisher's. */
+    confirmKey(id: string, publicKey: string, actor?: Actor): {
+        id: string;
+        url: string;
+        name: string | null;
+        signingMode: "signed" | "unsigned";
+        publicKey: string | null;
+        keyId: string | null;
+        keyStatus: "ok" | "key_changed";
+        /** When the key changed: the new key awaiting confirmation. */
+        offeredKey: {
+            publicKey: string;
+            keyId: string;
+        } | null;
+        pluginCount: number;
+        lastFetchedAt: Date | null;
+        lastFetchError: string | null;
+    };
+    remove(id: string, actor?: Actor): void;
+    /** Every plugin offered by every repo, with install/update state. */
+    available(): {
+        repoId: string;
+        repoName: string | null;
+        signingMode: "signed" | "unsigned";
+        pluginId: string;
+        name: string;
+        description: string | null;
+        versions: {
+            version: string;
+            compatible: boolean;
+        }[];
+        latest: string | null;
+        installed: {
+            version: string;
+            fromThisRepo: boolean;
+            source: "core" | "repo";
+        } | null;
+        updateAvailable: boolean;
+        blocked: string | null;
+    }[];
+    private get pluginsDir();
+    private get stagingDir();
+    /** Extracts regular files and directories only; links, devices and escaping paths fail the install. */
+    private extract;
+    install(raw: unknown, actor?: Actor): Promise<{
+        id: string;
+        pluginId: string;
+        version: string;
+        source: "core" | "repo";
+        repoId: string | null;
+        path: string;
+        sha256: string | null;
+        signatureVerified: boolean;
+        manifest: unknown;
+        status: "ok" | "invalid" | "incompatible";
+        statusError: string | null;
+        enabled: boolean;
+        installedAt: Date;
+    }>;
+    private installLocked;
+    /** Removes an installed (repo) plugin. Blocked while any instance uses it. */
+    uninstall(pluginRowOrId: string, actor?: Actor): void;
+}
+export {};