@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/ctx/namespace.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 断言 namespace 合法：仅小写字母、数字与 `-`。
+ * 各 ctx 工厂据此保证键 / 频道 / 队列名里的分隔符（`:`、`.`）不会出现在 namespace 内，
+ * 从而不同插件拼出的名字不可能相同。
+ */
+export declare function assertNamespace(namespace: string): void;

package/dist/ctx/namespace.js

@@ -0,0 +1,12 @@
+/** ctx 命名空间（即插件名）的合法形式，与 defineExtension 的 name 规则一致。 */
+const NAMESPACE_RE = /^[a-z][a-z0-9-]{1,40}$/;
+/**
+ * 断言 namespace 合法：仅小写字母、数字与 `-`。
+ * 各 ctx 工厂据此保证键 / 频道 / 队列名里的分隔符（`:`、`.`）不会出现在 namespace 内，
+ * 从而不同插件拼出的名字不可能相同。
+ */
+export function assertNamespace(namespace) {
+    if (typeof namespace !== "string" || !NAMESPACE_RE.test(namespace)) {
+        throw new TypeError(`ctx namespace must match ${NAMESPACE_RE}, got ${JSON.stringify(namespace)}`);
+    }
+}

package/dist/ctx/queue.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionContext, Logger } from "@capybara-hq/plugin-sdk";
+/**
+ * 创建 ctx.queue：BullMQ 队列名为 `cap.<namespace>.<name>`。namespace 经 assertNamespace 校验不含 `.`，
+ * 故第一个 `.` 之后的 namespace 段边界唯一，不同插件拼出的队列名不可能相同（`-` 作分隔符时
+ * `feishu` + `bot-sync` 与 `feishu-bot` + `sync` 会撞名）。BullMQ 只禁止 `:`，`.` 合法。
+ * runWorkers 为 false 时 define 只登记不创建 Worker（本进程不含 worker 角色）。
+ * 注意：jobId 去重只在任务仍被保留期间有效（removeOnComplete 1000 / removeOnFail 5000），
+ * 任务被清理后同 jobId 可再次入队。close() 之后 add/define 抛错。
+ */
+export declare function createQueue(redisUrl: string, namespace: string, opts: {
+    runWorkers: boolean;
+    log?: Pick<Logger, "error">;
+}): ExtensionContext["queue"] & {
+    close(): Promise<void>;
+    /** 停止取新任务（不等进行中的）：撤销插件实例的第一步。 */
+    pauseWorkers(): Promise<void>;
+    /** 等全部 worker 进行中的任务结束，最多等到 `deadline`（epoch 毫秒）；不关闭 worker。 */
+    drainWorkers(deadline: number): Promise<"drained" | "timeout">;
+    /**
+     * 关闭一个队列的 worker：不再取新任务，等进行中的任务结束，最多等到 `deadline`（epoch 毫秒）；到点仍未结束的
+     * 强制关闭——任务留在队列里（锁过期后按 stalled 交回等待），由新实例的 worker 接着处理（队列名不含版本）。
+     * 不给 `deadline` 时一直等到进行中的任务结束（停机路径）。没有 worker（本进程不含 worker 角色）时什么都不做。
+     */
+    stopWorker(name: string, deadline?: number): Promise<void>;
+};

package/dist/ctx/queue.js

@@ -0,0 +1,150 @@
+import { Queue, Worker } from "bullmq";
+import { Redis } from "ioredis";
+import { assertNamespace } from "./namespace.js";
+/** 未注入 logger 时的兜底：输出到 stderr。 */
+const consoleLog = {
+    error: (msg, fields) => console.error(`[queue] ${msg}`, fields ?? ""),
+};
+function assertNoColon(what, value) {
+    if (value.includes(":")) {
+        throw new TypeError(`${what} must not contain ":" (BullMQ restriction); use "-" instead`);
+    }
+}
+/**
+ * 创建 ctx.queue：BullMQ 队列名为 `cap.<namespace>.<name>`。namespace 经 assertNamespace 校验不含 `.`，
+ * 故第一个 `.` 之后的 namespace 段边界唯一，不同插件拼出的队列名不可能相同（`-` 作分隔符时
+ * `feishu` + `bot-sync` 与 `feishu-bot` + `sync` 会撞名）。BullMQ 只禁止 `:`，`.` 合法。
+ * runWorkers 为 false 时 define 只登记不创建 Worker（本进程不含 worker 角色）。
+ * 注意：jobId 去重只在任务仍被保留期间有效（removeOnComplete 1000 / removeOnFail 5000），
+ * 任务被清理后同 jobId 可再次入队。close() 之后 add/define 抛错。
+ */
+export function createQueue(redisUrl, namespace, opts) {
+    assertNamespace(namespace);
+    const log = opts.log ?? consoleLog;
+    const connections = [];
+    const queues = new Map();
+    const workers = new Map();
+    /** 每个 worker 进行中的任务数与「空了」的等待者（撤销时排空用）。 */
+    const active = new Map();
+    const defined = new Set();
+    let closed = false;
+    const assertOpen = () => {
+        if (closed)
+            throw new Error("queue is closed");
+    };
+    // BullMQ 要求 Worker 的阻塞连接 maxRetriesPerRequest 为 null；Queue 复用同样的配置。
+    const newConn = () => {
+        const c = new Redis(redisUrl, { maxRetriesPerRequest: null });
+        c.on("error", (err) => log.error("queue redis connection error", { err }));
+        connections.push(c);
+        return c;
+    };
+    const queueName = (name) => `cap.${namespace}.${name}`;
+    const getQueue = (name) => {
+        let q = queues.get(name);
+        if (!q) {
+            q = new Queue(queueName(name), { connection: newConn() });
+            q.on("error", (err) => log.error("queue error", { queue: name, err }));
+            queues.set(name, q);
+        }
+        return q;
+    };
+    return {
+        define(name, handler, o) {
+            assertOpen();
+            assertNoColon("queue name", name);
+            if (defined.has(name))
+                throw new Error(`queue "${name}" already defined`);
+            defined.add(name);
+            if (!opts.runWorkers)
+                return;
+            const st = { n: 0, idle: [] };
+            active.set(name, st);
+            const worker = new Worker(queueName(name), async (job) => {
+                st.n += 1;
+                try {
+                    await handler(job.data);
+                }
+                finally {
+                    st.n -= 1;
+                    if (st.n === 0)
+                        for (const w of st.idle.splice(0))
+                            w();
+                }
+            }, 
+            // 撤销插件实例时到点仍未完成的任务被强制留在队列里（锁过期后按 stalled 交回），新实例再执行一次：
+            // 任务是至少一次。stalled 次数放宽到 3，连续几次撤销 / 升级不至于把任务判为失败
+            { connection: newConn(), concurrency: o?.concurrency ?? 1, maxStalledCount: 3 });
+            worker.on("error", (err) => log.error("queue worker error", { queue: name, err }));
+            worker.on("failed", (job, err) => log.error("queue job failed", { queue: name, jobId: job?.id, err }));
+            workers.set(name, worker);
+        },
+        async add(name, data, o) {
+            assertOpen();
+            assertNoColon("queue name", name);
+            if (o?.jobId !== undefined)
+                assertNoColon("jobId", o.jobId);
+            await getQueue(name).add(name, data, {
+                ...(o?.jobId !== undefined && { jobId: o.jobId }),
+                ...(o?.delayMs !== undefined && { delay: o.delayMs }),
+                attempts: 3,
+                backoff: { type: "exponential", delay: 1000 },
+                removeOnComplete: 1000,
+                removeOnFail: 5000,
+            });
+        },
+        async pauseWorkers() {
+            await Promise.all([...workers.values()].map((w) => w.pause(true).catch(() => { })));
+        },
+        async drainWorkers(deadline) {
+            const busy = [...active.values()].filter((st) => st.n > 0);
+            if (busy.length === 0)
+                return "drained";
+            let timer;
+            try {
+                return await Promise.race([
+                    Promise.all(busy.map((st) => new Promise((resolve) => st.idle.push(resolve)))).then(() => "drained"),
+                    new Promise((resolve) => {
+                        timer = setTimeout(() => resolve("timeout"), Math.max(0, deadline - Date.now()));
+                    }),
+                ]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        async stopWorker(name, deadline) {
+            const w = workers.get(name);
+            if (!w)
+                return;
+            workers.delete(name);
+            const st = active.get(name);
+            active.delete(name);
+            if (deadline === undefined) {
+                await w.close();
+                return;
+            }
+            await w.pause(true).catch(() => { });
+            if (st && st.n > 0) {
+                let timer;
+                await Promise.race([
+                    new Promise((resolve) => st.idle.push(resolve)),
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, Math.max(0, deadline - Date.now()));
+                    }),
+                ]);
+                clearTimeout(timer);
+            }
+            await w.close(st !== undefined && st.n > 0);
+        },
+        async close() {
+            closed = true;
+            await Promise.all([...workers.values()].map((w) => w.close()));
+            await Promise.all([...queues.values()].map((q) => q.close()));
+            workers.clear();
+            queues.clear();
+            await Promise.all(connections.map((c) => c.quit().catch(() => c.disconnect())));
+            connections.length = 0;
+        },
+    };
+}

package/dist/ctx/secrets.d.ts

@@ -0,0 +1,45 @@
+import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
+import type { Kysely } from "kysely";
+/** 主密钥环：current 用于新包装，previous 仅用于解包。原始密钥只存在于闭包内。 */
+export interface Keyring {
+    readonly currentId: string;
+    /** 用当前主密钥包装（返回密文与所用主密钥 id）。 */
+    wrap(plain: Buffer, aad: string): {
+        data: Buffer;
+        masterKeyId: string;
+    };
+    /** 用指定 id 的主密钥解包；keyring 中没有该 id 时抛错（仅含 id，不含密钥）。 */
+    unwrap(masterKeyId: string, data: Buffer, aad: string): Buffer;
+    has(masterKeyId: string): boolean;
+    /**
+     * 为某一用途（`info`）从每把主密钥派生 32 字节子密钥（HKDF-SHA256，info = `capybara:<info>`）。
+     * 子密钥 id 与其主密钥 id 相同；原始主密钥不离开闭包。
+     */
+    deriveKey(info: string): DerivedKeys;
+    toJSON(): {
+        currentId: string;
+        previousIds: string[];
+    };
+}
+/** 某一用途的派生子密钥集合：current 用于签发，byId 用于按 id（= 主密钥 id）校验。 */
+export interface DerivedKeys {
+    currentId: string;
+    current: Buffer;
+    byId(id: string): Buffer | undefined;
+}
+/** 创建主密钥环；每把密钥必须恰为 32 字节。 */
+export declare function createKeyring(current: Buffer, previous: Buffer[]): Keyring;
+type AnyDb = Kysely<any>;
+/** 内核视角的 secrets：在 `ctx.secrets` 之上多一个 `delete`（插件契约不暴露）。 */
+export type KernelSecrets = ExtensionContext["secrets"] & {
+    /** 删除一个值；不存在时无操作。 */
+    delete(orgId: string, key: string): Promise<void>;
+};
+/**
+ * 实现 ctx.secrets：每组织一把数据密钥（信封加密），值密文绑定 namespace/org/key 位置。
+ * `db` 可以是 Kysely 事务：此时读写（含首次创建组织数据密钥）都在该事务内。
+ */
+export declare function createSecrets(db: AnyDb, keyring: Keyring, namespace: string): KernelSecrets;
+/** 把非当前主密钥包装的数据密钥改用当前主密钥重新包装，返回处理条数。 */
+export declare function rewrapDataKeys(db: AnyDb, keyring: Keyring): Promise<number>;
+export {};

package/dist/ctx/secrets.js

@@ -0,0 +1,175 @@
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
+import { assertNamespace } from "./namespace.js";
+const IV_LEN = 12;
+const TAG_LEN = 16;
+const KEY_LEN = 32;
+const derive = (key, info) => Buffer.from(hkdfSync("sha256", key, Buffer.alloc(0), `capybara:${info}`, KEY_LEN));
+const keyId = (key) => createHash("sha256").update(key).digest().subarray(0, 8).toString("hex");
+function seal(key, plain, aad) {
+    const iv = randomBytes(IV_LEN);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    cipher.setAAD(Buffer.from(aad, "utf8"));
+    const data = Buffer.concat([cipher.update(plain), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), data]);
+}
+function open(key, blob, aad) {
+    if (blob.length < IV_LEN + TAG_LEN)
+        throw new Error("secrets: ciphertext too short");
+    const decipher = createDecipheriv("aes-256-gcm", key, blob.subarray(0, IV_LEN));
+    decipher.setAAD(Buffer.from(aad, "utf8"));
+    decipher.setAuthTag(blob.subarray(IV_LEN, IV_LEN + TAG_LEN));
+    try {
+        return Buffer.concat([decipher.update(blob.subarray(IV_LEN + TAG_LEN)), decipher.final()]);
+    }
+    catch {
+        throw new Error("secrets: decryption failed (ciphertext corrupted, moved, or wrong key)");
+    }
+}
+/** 创建主密钥环；每把密钥必须恰为 32 字节。 */
+export function createKeyring(current, previous) {
+    for (const k of [current, ...previous]) {
+        if (!Buffer.isBuffer(k) || k.length !== KEY_LEN) {
+            throw new TypeError(`master key must be a ${KEY_LEN}-byte Buffer`);
+        }
+    }
+    const keys = new Map();
+    for (const k of [...previous, current])
+        keys.set(keyId(k), Buffer.from(k));
+    const currentId = keyId(current);
+    const currentKey = Buffer.from(current);
+    const ring = {
+        wrap: (plain, aad) => ({
+            data: seal(currentKey, plain, aad),
+            masterKeyId: currentId,
+        }),
+        unwrap(masterKeyId, data, aad) {
+            const key = keys.get(masterKeyId);
+            if (!key)
+                throw new Error(`secrets: master key ${masterKeyId} not found in keyring`);
+            return open(key, data, aad);
+        },
+        has: (id) => keys.has(id),
+        deriveKey(info) {
+            const derived = new Map();
+            for (const [id, k] of keys)
+                derived.set(id, derive(k, info));
+            const current = derived.get(currentId);
+            return {
+                currentId,
+                current: Buffer.from(current),
+                byId: (id) => {
+                    const d = derived.get(id);
+                    return d && Buffer.from(d);
+                },
+            };
+        },
+        toJSON: () => ({ currentId, previousIds: [...keys.keys()].filter((id) => id !== currentId) }),
+    };
+    Object.defineProperty(ring, "currentId", { value: currentId, enumerable: true });
+    return ring;
+}
+const dekAad = (orgId) => `org_data_key\0${orgId}`;
+const valueAad = (ns, orgId, key) => `${ns}\0${orgId}\0${key}`;
+async function loadDek(db, keyring, orgId, create) {
+    const select = () => db
+        .withSchema("capybara")
+        .selectFrom("org_data_keys")
+        .select(["wrapped_key", "master_key_id"])
+        .where("org_id", "=", orgId)
+        .executeTakeFirst();
+    let row = await select();
+    if (!row && create) {
+        const wrapped = keyring.wrap(randomBytes(KEY_LEN), dekAad(orgId));
+        // 多副本并发：先到先得，输家丢弃自己生成的密钥，重新读取赢家的
+        await db
+            .withSchema("capybara")
+            .insertInto("org_data_keys")
+            .values({ org_id: orgId, wrapped_key: wrapped.data, master_key_id: wrapped.masterKeyId })
+            .onConflict((oc) => oc.column("org_id").doNothing())
+            .execute();
+        row = await select();
+    }
+    if (!row)
+        return null;
+    return keyring.unwrap(row.master_key_id, Buffer.from(row.wrapped_key), dekAad(orgId));
+}
+/**
+ * 实现 ctx.secrets：每组织一把数据密钥（信封加密），值密文绑定 namespace/org/key 位置。
+ * `db` 可以是 Kysely 事务：此时读写（含首次创建组织数据密钥）都在该事务内。
+ */
+export function createSecrets(db, keyring, namespace) {
+    assertNamespace(namespace);
+    return {
+        async get(orgId, key) {
+            const row = await db
+                .withSchema("capybara")
+                .selectFrom("secrets")
+                .select("ciphertext")
+                .where("namespace", "=", namespace)
+                .where("org_id", "=", orgId)
+                .where("key", "=", key)
+                .executeTakeFirst();
+            if (!row)
+                return null;
+            const dek = await loadDek(db, keyring, orgId, false);
+            if (!dek)
+                throw new Error(`secrets: data key missing for org ${orgId}`);
+            return open(dek, Buffer.from(row.ciphertext), valueAad(namespace, orgId, key)).toString("utf8");
+        },
+        async set(orgId, key, value) {
+            const dek = await loadDek(db, keyring, orgId, true);
+            if (!dek)
+                throw new Error(`secrets: data key unavailable for org ${orgId}`);
+            const ciphertext = seal(dek, Buffer.from(value, "utf8"), valueAad(namespace, orgId, key));
+            await db
+                .withSchema("capybara")
+                .insertInto("secrets")
+                .values({ namespace, org_id: orgId, key, ciphertext })
+                .onConflict((oc) => oc.columns(["namespace", "org_id", "key"]).doUpdateSet({
+                ciphertext,
+                updated_at: new Date(),
+            }))
+                .execute();
+        },
+        async delete(orgId, key) {
+            await db
+                .withSchema("capybara")
+                .deleteFrom("secrets")
+                .where("namespace", "=", namespace)
+                .where("org_id", "=", orgId)
+                .where("key", "=", key)
+                .execute();
+        },
+    };
+}
+/** 把非当前主密钥包装的数据密钥改用当前主密钥重新包装，返回处理条数。 */
+export async function rewrapDataKeys(db, keyring) {
+    return db.transaction().execute(async (trx) => {
+        const rows = await trx
+            .withSchema("capybara")
+            .selectFrom("org_data_keys")
+            .select(["org_id", "wrapped_key", "master_key_id"])
+            .where("master_key_id", "!=", keyring.currentId)
+            .orderBy("org_id")
+            .forUpdate()
+            .execute();
+        const unknown = rows.filter((r) => !keyring.has(r.master_key_id));
+        if (unknown.length > 0) {
+            const shown = unknown
+                .slice(0, 20)
+                .map((r) => `${r.org_id}(master_key_id=${r.master_key_id})`);
+            throw new Error(`secrets: master key not in keyring for org_id: ${shown.join(", ")}`);
+        }
+        for (const r of rows) {
+            const dek = keyring.unwrap(r.master_key_id, Buffer.from(r.wrapped_key), dekAad(r.org_id));
+            const w = keyring.wrap(dek, dekAad(r.org_id));
+            await trx
+                .withSchema("capybara")
+                .updateTable("org_data_keys")
+                .set({ wrapped_key: w.data, master_key_id: w.masterKeyId })
+                .where("org_id", "=", r.org_id)
+                .execute();
+        }
+        return rows.length;
+    });
+}